cli: `serve`'s dynamic cluster-driver import cannot resolve app-declared `@objectstack/service-cluster*` — EE multi-node `OS_CLUSTER_DRIVER=redis` dies at boot

[os-zhuang]

Origin: triage split from objectstack-ai/cloud#1502 (EE 4.1.0 published-image acceptance, measured on ghcr.io/objectstack-ai/objectos-ee@sha256:20fc4ab5…). Filed by the triage seat; the cloud-side legs (deploy README, CI leg, ADR-0010 direction) stay on the source card.

Symptom (measured on the published image)

With OS_CLUSTER_DRIVER=redis set (the deploy README's recommended production multi-node path), boot dies:

✗ Cannot find package '@objectstack/service-cluster' imported from
 /repo/objectstack/packages/cli/dist/commands/serve.js

migrate exits 1, and compose's service_completed_successfully condition takes the whole stack down with it. Triggered by requesting the redis driver at all — replicas declared or not.

Root cause

Module-resolution asymmetry measured inside the image:

• /repo/objectstack/packages/cli/node_modules/@objectstack/ holds 48 packages — no service-cluster / service-cluster-redis;
• both are installed only under the app (apps/objectos-ee/package.json declares them).

serve.ts reaches the driver via dynamic imports (packages/cli/src/commands/serve.ts:1425 '@objectstack/service-cluster', :1456 `@objectstack/service-cluster-${driver}`) that resolve from the CLI's own location and cannot cross the link: boundary. App-side code CAN load the same packages (the ClusterServicePlugin multi-node guard runs fine), so only the CLI-side hop is broken. Same class as the earlier AI-Studio-plugin CLI auto-discovery resolution defect.

PM 建议的路线(可选,实测优先)

Either declare service-cluster (+ shipped drivers) as CLI dependencies, or resolve the dynamic import with createRequire anchored at the app's config directory — the general fix should cover any app-declared optional package the CLI advertises it will load, not just this driver.

Notes

• Direction-independent of the ADR-0010 question held on cloud#1502 (needs-user-decision: whether EE recommends redis at all). Whatever that ruling says, a CLI that names @objectstack/service-cluster-redis in its own refusal guidance must be able to load it when the app declares it.
• Downstream: cloud#1502 (priority:p0) is blocked on this card.
• File surface: packages/cli/src/commands/serve.ts (+ possibly packages/cli/package.json). Mind serve-multi-node-cap-advisory.pin.test.ts, which pins the current dynamic-import shape.

[os-elon]

Claim: domain:cli lane execution seat
Session: session_019bmVFqoQPq63zhKrxdYG1r
Branch: claude/issue-10645-cli-cluster-driver-resolution
Worktree: objectstack-issue-10645
Domain: domain:cli
File surface: packages/cli/src/commands/serve.ts (the two dynamic imports) and, if the chosen route needs it, packages/cli/package.json. ⛔ Re-derive both line anchors at head — the card's :1425 / :1456 are from a named ref and the file moves.
Container & model: M, mode:subagent, model: opus
Clause-②: no — this fixes where a module is resolved from. No request is accepted or refused differently, and no public surface widens. ⚠️ If your route turns out to change what serve accepts or refuses, you have left the card — STOP and report.
Serial constraints cleared: measured, not assumed — all 13 open PRs listed and checked; none touches packages/cli/src/commands/serve.ts. See the pin hazard below for the one adjacent card.

The bug is measured, the route is not — measure before you choose

Triage filed this from a real published-image acceptance run, so ⛔ do not re-litigate the symptom. What is not settled is the fix. The card offers two routes and says "实测优先":

• (A) declare service-cluster (+ shipped drivers) as packages/cli dependencies;
• (B) resolve the dynamic import with createRequire anchored at the app's config directory.

⭐ The card states the acceptance criterion that should decide it, and it is wider than this driver: "the general fix should cover any app-declared optional package the CLI advertises it will load, not just this driver." Route (A) satisfies the symptom and fails that criterion — it fixes exactly the packages you happen to list, and the next app-declared optional package breaks identically. Weigh that explicitly and say which route you took and why.

Reproduce the resolution asymmetry before fixing it: the CLI's own node_modules/@objectstack/ has no service-cluster, the app's does, and app-side code loads it fine — so the failing hop is specifically CLI→app. A fix that does not demonstrably cross that boundary has not been verified.

⚠️ Pin hazard — read this before you touch the import shape

packages/cli/src/commands/serve-multi-node-cap-advisory.pin.test.ts pins the current dynamic-import shape. Your fix will likely move it. That pin is a contract, not scaffolding:

• ⛔ Do not edit an assertion to make it agree with your change. If the pin goes red, the question is whether the pinned shape is still the right thing to pin — report that as a fork, don't resolve it by rewriting the expectation.
• ⚠️ That same file is the subject of Two packages/cli scans read serve.ts with no comment/code separator at all, so prose counts as code — the direction js-comment-mask's header calls the worse one #10514 (pm:blocked, unassigned, no branch — nothing in flight, so there is nothing to serialize against). Two packages/cli scans read serve.ts with no comment/code separator at all, so prose counts as code — the direction js-comment-mask's header calls the worse one #10514 will route its scans through maskComments. If you change the import shape, say so in your report so whoever takes Two packages/cli scans read serve.ts with no comment/code separator at all, so prose counts as code — the direction js-comment-mask's header calls the worse one #10514 re-derives rather than inherits.

Note the pin's own scanner reads serve.ts raw, comments included (that is #10514's defect). So a change you make only in a comment can move that pin's verdict. Worth knowing if it goes red for a reason that looks impossible.

Fences

• ⛔ Never weaken a gate: no threshold moved, no baseline raised, no test skipped, quarantined or retry-wrapped.
• ⛔ Nothing under content/docs/releases/**. Your changeset is the release-notes input.
• ⚠️ objectstack-ai/cloud#1502 (priority:p0) is blocked on this card and is cross-repo — out of this seat's scope. ⛔ Do not attempt to touch it; just don't break the contract it is waiting on.

⚠️ 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

[os-elon]

os-dev-report

{
 "issue": 10645,
 "status": "done",
 "branch": "claude/issue-10645-cli-cluster-driver-resolution",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/10765",
 "premise_still_valid": true,
 "summary": "Card premise verified at head: both line anchors still land (serve.ts:1425 '@objectstack/service-cluster', :1456 the driver template literal), and packages/cli declares neither cluster package. Took route (B): both cluster loads now go through createHostImporter from @objectstack/types/node — the host-anchored, declaration-gated importer serve ALREADY used further down for its organizations and capability loads, so nothing new was invented and the fix covers any app-declared optional package, satisfying the card's stated criterion. Rejected route (A): declaring the packages as CLI deps fixes exactly the listed packages, leaves a third-party driver unloadable forever, and would give the open-core CLI a static dependency on distribution-shipped packages — the exact coupling the non-literal specifier exists to avoid. Second, load-bearing half: importFromHost was defined at ~:2128 while the cluster block sits at ~:1425, so those loads could never have reached it; it is a const in one long boot function, so a load above it is not a compile error but a silent fall-back to bare resolution. Hoisted it to the top of the boot sequence. This is the SECOND time that shape shipped a defect — it previously sat below the auth block and cost the enterprise organizations load (cloud#1013). Clause-② holds: only where a module is resolved FROM changed; the #4719 declaration gate is untouched and a test asserts an undeclared package is still refused.",
 "tests": "Reproduced the asymmetry BEFORE fixing, from inside packages/cli (same resolution base as the shipped dist/commands/serve.js) against a fixture app declaring the packages: 'LEG1 bare import(): THREW code=ERR_MODULE_NOT_FOUND / Cannot find package '@objectstack/service-cluster' imported from .../packages/cli/repro-probe.mjs' and 'LEG2 createHostImporter(app): LOADED exports checkMultiNodeAllowed=function' — same error string as the card's measured symptom, and the fix demonstrably crosses the CLI→app boundary. New test packages/cli/src/commands/serve-cluster-host-resolution.test.ts (8 tests): 3 behavioural/hermetic (a synthetic package present only in a fixture app's node_modules is invisible to a bare import and IS loadable via the host importer; undeclared is still refused) + 5 source-scan (loads go through importFromHost, never a bare import, helper defined ABOVE the block, exactly one definition). Targeted run: 'Test Files 3 passed (3) / Tests 20 passed (20)' (new file + serve-multi-node-cap-advisory.pin.test.ts + serve-multi-node-cap-advisory.test.ts). ABLATION, direction predicted before running and matched: serve.ts reverted to origin/main gave 'Tests 3 failed | 8 passed (11)' — the 3 red are exactly the source-shape assertions (ordering, host-importer use, no-bare-import); the 3 behavioural ones stayed GREEN because they exercise createHostImporter directly, not serve.ts. Restore leg re-run green: 'Test Files 2 passed (2) / Tests 11 passed (11)'. REBUILD STATEMENT: neither ablation leg required a rebuild and none was performed — the mutated subject (serve.ts) is consumed by the failing assertions as SOURCE TEXT read from src via readFileSync, so no dist/ sits between the mutation and the assertion; the only dist-resolved import (@objectstack/types/node) was not mutated in either leg. PIN: serve-multi-node-cap-advisory.pin.test.ts is GREEN both before and after, and passed in the ablation run against origin/main's serve.ts too — its assertions pin the gate call's arity, the OS_CLUSTER_REPLICAS argument and the hand-written verdict cast, none of which is touched by swapping 'import(' for 'importFromHost('. NO assertion in it was edited and there is no fork to arbitrate. Gates re-derived AFTER the final commit with 'node scripts/pm/dispatch-gates.mjs' (no paths passed) rather than inherited, and all run on cba91346c2 with a clean tree: check:nul-bytes, check:changeset-gate-self-tests, check:objectui-changeset, check:route-envelope, check:cross-package-test-inputs, check:slot-lookup, check:test-source-alias, check:type-source-resolution, check:engine-double-contract, check:where-matcher, check:query-options-erasure, check:type-check-coverage, check-adr-0087-registration.mjs, check-changeset-no-major.mjs, check-empty-changeset.mjs, check-cross-package-test-inputs.mjs, docs-audit/check-affected-docs.mjs — all EXIT=0 (captured before any pipe). 'pnpm --filter @objectstack/cli typecheck' → os-verify-lock VERDICT command-exit 0, with '> tsc --noEmit' echoed in the output confirming a real run and not a zero-match. Ratchet after a full workspace build (Tasks: 70 successful, 70 total): 'check-type-check-coverage --re-measure: OK — 33 ledger entr(ies) re-measured in 266.6s, 1912 raw tsc error(s) total, none above its recorded number.' The 12-error plugin-auth surplus it reports is pre-existing and untouched by this diff. Every heavy run went through scripts/pm/os-verify-lock.sh and verdicts are quoted from its VERDICT lines, never a bare $?.",
 "open_questions": [],
 "out_of_scope_findings": []
}

Notes for the PM, outside the JSON:

• Two packages/cli scans read serve.ts with no comment/code separator at all, so prose counts as code — the direction js-comment-mask's header calls the worse one #10514 (the pin's maskComments card) needs a re-derive, not an inherit. The dynamic-import expression in the cluster block changed shape (await import(__clusterPkg) → await importFromHost(__clusterPkg)), and two explanatory comments were added inside the block the pin's scanner reads raw. The pin is green today, but whoever picks up Two packages/cli scans read serve.ts with no comment/code separator at all, so prose counts as code — the direction js-comment-mask's header calls the worse one #10514 should re-derive its scan targets against the new text rather than working from the card's description of the old one.
• Nothing was filed as an out-of-scope finding. The one adjacent defect I noticed is already tracked: packages/cli/src/utils/optional-package.ts resolves optional packages from the CLI's own location (import.meta.resolve, "resolves from THIS module"), so it carries the same CLI→app blind spot for any caller that uses it on an app-declared package. I did not file it because it is the same defect class as this card under a different helper and its current callers (os doctor) are framework-owned loads where CLI-anchored resolution is correct — but it is the next place this class will surface, and it is a real candidate if you want the class closed rather than the site.

---

Generated by Claude Code