kernel

• 状态：In progress
• 实现状态：preview npm 包已初始化；确定性基础 API 已实现并有单元测试。
• 架构依据：ADR-001、ADR-002

计划职责

以 @fluffy-glass/engine-core 发布固定 Tick、模拟时间契约、命令信封、稳定排序、命名 seeded PRNG、canonical 编码、快照/状态 hash、Tick trace、内存录制/回放，以及不依赖传输、呈现或存储的 headless 核心抽象。

允许依赖

@fluffy-glass/engine-shard 的 scalar contracts，以及标准语言能力。Core 继续从其根入口兼容重导出既有 scalar API。

禁止依赖

Hono、Godot、SQLite、WebSocket 以及具体 host 实现。

模拟时间

默认 SimulationTimeConfig 将一个 Tick 定义为 9,000 模拟毫秒。以外部 host 的 10 Hz 1× 播放为例，一个模拟日包含 9,600 Tick，对应 16 分钟现实时间。内核只从 Tick 推导模拟时间；暂停、倍速、catch-up 与墙钟调度属于 host/UI，不能改变单个 Tick 表示的模拟时长。

调试与回放契约

hashCanonicalState 将 canonical value 编码后生成 StateHash。DeterministicSimulation 可选地通过 stateHasher 和 onTrace 发布每 Tick 已稳定排序的命令、checkpoint 标记与 state hash。SimulationRecorder 只在调用方确认命令成功 enqueue 后记录命令和 checkpoint；replayRecording 从调用方提供的独立初始状态工厂重新执行并比较 checkpoint hash。

这些 API 都是内存、headless 契约：不进行文件写入、状态泛型深拷贝、网络传输或终端渲染。replayRecording 会在推进前验证 recording、时间配置、checkpoint 和命令排序键；默认 checkpoint 失配会抛出 ReplayCheckpointMismatchError，其包含预期/实际 hash 和稳定排序的 Tick 命令上下文。assertSimulationTraceRecord 可验证通用 trace 完整性。snapshot() 只隔离数组和时间配置，不深拷贝 command payload 或初始状态工厂。restoreSnapshot 由调用方提供 decoder 和 state hash 校验，并从快照 Tick 继续 replay；快照 bytes 的编码、持久化、迁移和 content compatibility 仍由后续适配器负责。

版本兼容

Core 目前精确支持 schema v1。CommandEnvelope 在 queue/replay 边界、SimulationTimeConfig 在 simulation/replay 边界、SimulationRecording 与 checkpoint 在 replay 边界，以及 SnapshotMetadata 在 createSnapshot/restoreSnapshot 边界都会拒绝未知版本。snapshot metadata 只接受 canonical-v1；其跨语言 bytes/digest conformance fixture 位于仓库根目录 fixtures/canonical-v1.json。snapshot bytes 仍是不透明的内存数据，恢复需要调用方提供 decoder 和 state hash 校验，但不提供持久化或迁移兼容承诺。trace 只由 Core 生成，未定义外部输入兼容面。

当前不包含

不包含领域政策、运行时 SoA/TypedArray 存储、规则 VM、交通图、Worker 生命周期或持久化适配器。公开 API 仅从包根入口导出。