moonswim

SWIM 集群成员管理纯核(MoonBit):带疑似中间态(Susp)的四态成员账、 incarnation 单调拒旧账、怀疑超窗确认扫描、反熵话术传播——Bring Your Own Everything:身份在 port 后(Identity),核只认语义事件 MemberEvent,只出”该记什么账、该向谁要活”;编解码(wire)、探测 (probe)、传输(link)是可整包替换的参考实现。千里传音之外的另一课: 如何知道合唱团里谁还在唱。

血统明示

SWIM 思想致敬(Das et al. 2002,SWIM: Scalable Weakly-consistent Infection-style Process Group Membership;foca 形的 BYO 切面)—— 思想与形态致敬,线全自研 clean-room:状态机迁移表、事件词表、 账本律、API 形全部自定义,不与 foca / memberlist 线级互通。 架构契约蓝图:vox1000 .mingspace/swim_gossip_ming.md(2026-11-02)。

包结构

包	职责	入口
thy1016/moonswim/core	语义簇:成员表状态机纯核(Identity port 逐字节全序 / 四态成员账 incarnation 单调律 / 怀疑超窗确认 / 话术队列与降格契约)	Swim::new → Swim::apply / drain_rumors / Rumor::to_evidence
thy1016/moonswim/wire	文法簇:Rumor 定长帧编解码(版本位/kind 封闭词表/逐字节金罐/负例全闸)	encode_rumor / decode_evidence
thy1016/moonswim/sim	双节点对打宿主(emit/receive/deliver 三动程;拒旧账闸住宿主面;对打测试与演示的家)	Duet::new → deliver
thy1016/moonswim/probe	探测引擎纯形宿主(注入钟周期轮转/截止窗升级间接/双败判嫌——终态两径,引擎只产嫌疑)	ProbeEngine::new → on_tick / on_frame
thy1016/moonswim/link	UDP 真缝(UdpPump 收发分离:后台收件永不取消+主环泵快照式结算;id↔Addr 装配面注册)	UdpPump::listen → pump

gen 链(大 gen 宪法):迁移状态机是生成面——表源 member_fsm.toml(16 格显式穷尽,唯一事实源)→ 主仓 skelgen/swimgen(moonswim 专用方言户)发 core/gen.mbt(禁手编); 律法动作(touch/rejoin)住 core/member_law.mbt,账面印章住 core/types.mbt,适配面三段律(离场预滤/印章重铸/入场律)住 core/swim.mbt。黄金门 = regen 原始形 + fmt ≡ 入库逐字节(主仓仓根 moon test skelgen/swimgen)。

核心零依赖(契约律 2):core 无 async、无传输、无密码学;时间 = tick 显式入参,钟在核外(probe 引擎同守:注入钟,零 IO)。模块唯一 外依 moonbitlang/async 只住 link 缝(native 档);wire/probe/sim 零 async。消费方自带编解码/传输时,import core 一包即可。纯包四件 (core/wire/probe/sim)全后端可用(wasm-gc / wasm / js / native)。

安装

moon add thy1016/moonswim

按需在 moon.pkg 引包:thy1016/moonswim/core(纯核,必选)、wire (参考帧编解码)、probe(探测引擎)——三者全后端;link(UDP 真缝) 只在 native 档。

快速上手

成员表入账 → 账变即入队 → 按字节预算倾倒话术编帧上线(传输自带, 或用 link 真缝):

let table = @core.Swim::new(self_bytes=me, suspect_timeout_ticks=100L)
table.apply(
  id_bytes=peer_id,
  report=@core.MemberAliveEvidence({
    tick: 0,
    from_self: false,
    claimed_incarnation: 0L,
  }),
)
for rumor in table.drain_rumors(budget_bytes=512) {
  send(@wire.encode_rumor(rumor)) // send = 消费方传输
}
let _ = table.confirm_suspects(tick=now) // 怀疑超窗坐实(本地之钟)

对端收帧:解码 → 拒旧账闸 → 降格为非终态证据 → 入账(远端话术永不 直书终态):

fn feed(peer : @core.Swim, frame : Bytes, tick~ : Int64) -> Bool {
  let rumor = @wire.decode_rumor(frame) catch { _ => return false }
  let stale = match peer.get(rumor.id_bytes) {
    Some(account) => rumor.stale_against(account)
    None => false
  }
  if stale {
    return false
  }
  peer.apply(id_bytes=rumor.id_bytes, report=rumor.to_evidence(tick~))
  true
}

完整可跑版:moon run examples/quickstart(全后端)——三节点话术一程, 演示话术降格律(A 坐实的死讯到 C 只是嫌疑)与终态两径律(C 用自己的 钟坐实才达终态)。

探测与真缝示例:probe/probe_test.mbt(六行为罐:注入钟驱动 on_tick / on_frame)、link/udp_link_test.mbt(双泵真 UDP 回环: UdpPump::listen → register_peer → spawn_recv → 周期 pump)。

测试与验证

moon check --deny-warn       # 零错零警(缺省 native 档)
moon test                    # native 25 罐:core 7(守恒/话术/降格契约/序免疫锚)
                             # + wire 6(金罐 + 负例全闸)+ probe 6(行为罐)
                             # + sim 5(对打 + 探测联测)+ link 1(真 UDP 回环)
moon test --target wasm-gc   # 纯包四件 24 罐(wasm / js 同)
moon fmt && moon info        # 格式与接口面漂移门

link 回环罐走本机 127.0.0.1 真 UDP(时序断言全取下界形,N 跑定稳)。

账本律(spec §3)逐条罐钉:Down/Left 终态不翻,且只认本人 Leave 与 本地扫描坐实两径(远端话术一律降格为非终态证据);同账 incarnation 只增不减(本人否认 +1,他人证据采信 max(账面,来章));旧周期话术 拒收;无账嫌疑/离场话术不动账;bytes_lt 逐字节序免疫锚(“b” vs “ab” 长度序陷阱的负例钉)。

演进位(不预铺,随役立)

已落:反熵话术队列(K1)/ wire 文法簇(K2)/ sim 对打(K3)/ probe 探测引擎(K4)/ link UDP 真缝(K5)。候役:

• 话术上真缝(Rumor piggyback 挂探针报文;复合报文 = 新帧布局族, 开役前过文法面五律⑤评估);
• 发现面适配(T5:vox1000 SeamNet ↔ UdpPump;缝现只做 id↔Addr 静态 注册);
• 跨机真网判读(活性收敛秒/误判率,T5 部署环境)。

许可证

Apache-2.0(Apache License 2.0),全文见 LICENSE。