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)

[baozhoutao]

Symptom

On the objectos-ee image (framework pinned at 502ff8b5), a 3-replica boot with OS_CLUSTER_DRIVER=redis + OS_REDIS_URL dies at kernel init:

✗ Cluster driver "redis" is not registered. Did you forget to import @objectstack/service-cluster-redis or call registerClusterDriver()? See content/docs/kernel/cluster.mdx §6.

@objectstack/service-cluster-redis IS declared by the app and IS resolvable — a bare import('@objectstack/service-cluster-redis') from the app root succeeds. #10645's fix (host-anchored resolution) is in place and the load itself no longer fails. Something else eats the registration.

Root cause — module-instance split at the importFromHost seam

serve.ts loads the driver via importFromHost('@objectstack/service-cluster-<driver>') (serve.ts:1919). For a declared package, createHostImporter (packages/types/src/node.ts) resolves it with hostRequire.resolve(pkg) — a CommonJS resolution that returns the package's main, i.e. dist/index.cjs — then does import(pathToFileURL(resolved).href).

So the driver executes as its CJS build, and its self-registration registerClusterDriver('redis', …) runs against the CJS copy of @objectstack/service-cluster's module-scope registry.

Meanwhile packages/cli is "type": "module": serve → new Runtime(...) → @objectstack/service-cluster all load as ESM, and defineCluster() consults the ESM copy of the registry — which is empty.

Measured inside the running image (same process, both instances probed):

ESM instance: redis REGISTERED ← after a bare import('@objectstack/service-cluster-redis')
CJS instance: NOT registered: Cluster driver "redis" is not registered…

The silent catch { /* may already be registered by the loaded config */ } around the serve-side load (serve.ts:1920) means the split produces no diagnostic at all — the boot just fails one line later in defineCluster, or (with a gate denying) silently runs split-brain-guarded single-node.

Impact

• OS_CLUSTER_DRIVER=redis cannot activate on any config-boot app whose driver package ships a CJS main (every tsup dual build does). This is the shipped EE multi-node path from cloud/apps/objectos-ee/docker-compose.yml (ADR-0018).
• The same seam presumably affects any importFromHost-loaded package whose side effect must land in a module-scope registry read by the ESM chain (registerMultiNodeGate from a CJS-evaluated config has the mirror-image problem — the EE licence gate registered from config is invisible to an ESM-side reader, and vice versa).

Repro

1. Build the EE image at this pin, run cloud/apps/objectos-ee/docker-compose.yml with --scale app=3 (redis driver env preset there).
2. migrate exits 1 with the "not registered" error above.

Workaround (verified)

Registering from the app config lands in the ESM registry the Runtime actually reads (the config is evaluated as ESM):

// objectstack.config.ts
import '@objectstack/service-cluster-redis';

With this line, the same 3-replica compose boots, the redis driver activates, and cross-node locks (os:lock:* / os:fence:*) appear in redis.

Possible fixes

• In createHostImporter's declared leg, resolve with ESM semantics (import.meta.resolve-equivalent honoring the import condition) instead of hostRequire.resolve, so the same build of a package is loaded on both sides; or
• have the driver packages register into a registry that is instance-split-proof (e.g. keyed on globalThis), which also hardens every other module-scope registry against dual-build loading; or
• at minimum, drop the silent catch: log the load error and, after the load, verify the driver is visible to the registry the Runtime will read, so the split reports itself instead of surfacing as "not registered" one line later.

Found during a 3-replica EE cluster deployment verification (2026-08-30); companion report in cloud branch claude/enterprise-cluster-deployment-qxiexe.

[os-warren]

分诊 → domain:cli · p1 · bug。本卡为该缺陷的正卡；#13365 是同一缺陷的重复卡，已合并到这里（理由见下）。

锚定。 三条候选修复路径：① createHostImporter 的 declared 分支改走 ESM 条件解析（packages/types/src/node.ts ⇒ domain:cli）；③ serve 端不再静默吞错 + 装载后验证注册可见性（packages/cli/src/commands/serve.ts ⇒ domain:cli）；② registry 挂 globalThis（packages/services/service-cluster/src/cluster.ts ⇒ domain:services）。根因在 ①，主车道 domain:cli，② 作为跨域半边由该车道 PM 在认领评论申报文件面。

在当前 origin/main 上复核了 ③（行号已漂移，按现树重新给）：

packages/cli/src/commands/serve.ts
:2469 // Same host-anchored resolution as the gate above — the shipped
:2470 // drivers (`-redis`, `-postgres`, …) are app-declared too. The catch
:2471 // stays deliberately silent: the driver may already have been
:2472 // registered by the loaded config, and an absent driver is a
:2473 // documented fall-back to the in-memory cluster, not a boot failure.
:2474 try { await importFromHost(`@objectstack/service-cluster-${__clusterDriver}`); }
:2475 catch { /* may already be registered by the loaded config */ }

这条 catch 是有意写的，注释给了两条理由 —— 而两条都是假设而不是读数。这正是本卡建议 ③ 的要害，请写进派单：修复不是「删掉 catch」，是把假设换成读数 —— 装载后查 Runtime 将要读的那张 registry，查不到才决定是降级还是报错。⛔ 不要改成直接抛：缺驱动降级到 in-memory 是文档化行为，直接抛会把可用部署变成拒启。

与 #13365 的合并

#13365（同一报告方，晚 3 小时 15 分）描述的是同一条缺陷：同一个 importFromHost 接缝、同一次 CJS/ESM 双实例错位、同一条静默 catch、同一个 Cluster driver "redis" is not registered 症状。以本卡为正卡，因为它带决定性读数 —— 同进程内同时探两个实例：

ESM instance: redis REGISTERED ← after a bare import('@objectstack/service-cluster-redis')
CJS instance: NOT registered: Cluster driver "redis" is not registered…

从 #13365 带过来、本卡没有的两项：

• 另一个已验证绕法：入口改 node --import cluster-preload.mjs，在宿主目录以纯 ESM await import() 预载一次。实测 3 副本集群恢复（redis fence 锁选主、跨副本协调均工作）。与本卡的 objectstack.config.ts 里加一行 import 相比，后者更简单，推荐作为对外给运维的绕法；预载脚本适用于不便改 config 的镜像。收录在 steedos-labs/os-project-titanwind-ehr PR docs: finish implementation-accuracy audit (remaining 82 hand-written docs + generated references) #1880 的 deploy-ee/README.md。
• cloud 侧连带缺口已立卡：objectstack-ai/cloud#1752（registerMultiNodeGate 的同型双实例错位 + 只在 EE config 接线）。那是 cloud 座位的卡，本卡不代管；⛔ 若两边同批修，走跨座位路径，不要在一个 PR 里跨仓。

定级 p1。 现场报告，后果是已发货的 EE 多节点路径（ADR-0018）无法激活集群驱动，migrate 直接 exit 1。有一行 config 的已验证绕法，所以不是 p0 —— 相邻的 #13331 没有绕法，那张是 p0。

排序：#13330（本卡）→ #13331。#13331 的集群内验证需要先有本卡的绕法或修复才能观察；交给同一个 dev 连着做最省。

另一处历史读数：serve.ts:711 的文档块已记过同一症状（OS_CLUSTER_DRIVER=redis 镜像启动 Cannot find package）。派单前读那段，可能已排除掉一部分假设。

---

Generated by Claude Code