Cell 注册表

wesgine Hypervisor 的 Cell 注册表管理机制。

定位

Cell 注册表（internal/hypervisor/registry/）是 Hypervisor 管理 Cell 生命周期的核心组件。

它维护 Cell ID 与 Cell 实例之间的映射关系。

不变量

INV-CELL-06：身份连续

registry 有 ID ⇔ 内存必有骨架（Stopped 除外）。

Get 未命中必须 hydrate；restore/Create 失败不得把仍注册的目录当孤儿改名。

INV-CELL-07：孤儿目录改名

孤儿目录改名仅在 registry.Create 成功之后。

INV-CELL-08：Cell 启动条件

Cell.Start/WarmUp 合法输入 = 身份 + 已 Bind 的进程 hook。

live-token 且 ProviderLiveKeyFn==nil 时 fail-loud。

Hypervisor Cells Handle

Create

cell, err := hyp.Cells().Create(ctx, CellSpec{...})

创建新 Cell。ID 冲突报错。

Get

cell, err := hyp.Cells().Get(cellID)

内存未命中则 hydrate 骨架，不 Start。

GetOrCreate

cell, err := hyp.Cells().GetOrCreate(ctx, CellSpec{...})

merge json:"-" hook 后 EnsureActive。

List

summaries, err := hyp.Cells().List(ctx)

Stop / Delete

err := hyp.Cells().Stop(ctx, cellID)
err := hyp.Cells().Delete(ctx, cellID) // registry 行 + 磁盘字节都删

UpdateSpec

err := hyp.Cells().UpdateSpec(ctx, cellID, patch)

通过 SpecPatch 部分更新 CellSpec。

Restart / ResetFaults

err := hyp.Cells().Restart(ctx, cellID)
err := hyp.Cells().ResetFaults(ctx, cellID)

Admin HTTP 端点

GET    /admin/cells
POST   /admin/cells
POST   /admin/cells/import
GET    /admin/cells/{id}
PATCH  /admin/cells/{id}
PUT    /admin/cells/{id}       # 幂等 upsert（GetOrCreate）
DELETE /admin/cells/{id}
POST   /admin/cells/{id}/stop
POST   /admin/cells/{id}/restart
POST   /admin/cells/{id}/reset-faults
GET    /admin/cells/{id}/export
POST   /admin/cells/{id}/providers/{name}/probe

启动顺序（INV-SERVE-REACHABLE-01）

hyp.Start(ctx)           → 只挂身份骨架（Cool/Cold），永不 Cell.Start
GetOrCreate(ctx, spec)   → Bind+Activate（SDK 路径）
ActivatePersisted(ctx)   → HTTP serve 之后后台打开数据面

hyp.Start 永不 Cell.Start。

ActivatePersisted 在监听之后后台运行，保证可达性不随租户数增长。