docs(03-02): record approved event built-in contract

- Record all eight approved built-in names and parameter fields
- Lock safe failure, awaited actions, and top-level registration seam

.planning/phases/03-data-completion/03-EVENT-CONTRACT.md

@@ -0,0 +1,136 @@
+# Phase 3 Event Built-in Contract
+
+本文件记录 `confirm-record` checkpoint 的确认结果。范围只包含本阶段批准的八个
+event built-ins；不加入完整 legacy 事件目录，不保留未决字段，也不把渲染行为放入
+数据端函数。
+
+## Shared contract
+
+- 每个函数都使用 `(param, env)` 调用形式。
+- `env` 的类型固定为 `IBlockEventEnv`。目标解析顺序为：明确的
+  `env.layer`，`env.map` 的 `eventLayer`，最后是通过 `env.heroFloor` 从
+  `env.state.maps` 获取的地图及其 `eventLayer`。
+- 目标、图块、勇士、事件存储或事件 id 缺失时，函数安全跳过并返回 `void`；不抛出
+  业务错误，不访问 DOM、render global 或 legacy global。
+- 地图删除、移动、勇士移动和临时事件序列都等待完整的 Promise 动作；没有需要等待
+  的动作时同步返回 `void`。
+- 默认注册项由 `data-state/src/event` 提供，`CoreState` 只负责把注册项传给
+  `GameEventSystem`；`GameEventSystem` 通过现有 `AnonTokyoInterpreter` 的
+  `builtInFunctions` 初始化项装配。函数实现不复制到 `CoreState`。
+- 注册项只包含下表八个稳定名称。
+
+## Parameter contracts
+
+### `eventSetBlock`
+
+```ts
+interface ISetBlockEventParam {
+    readonly x: number;
+    readonly y: number;
+    readonly tile: number | string;
+}
+```
+
+在解析出的目标图层设置 `(x, y)` 的静态图块。`tile` 通过 `env.state.tileStore`
+解析；图块 id、地图、图层或坐标目标不可用时安全返回 `void`。
+
+### `eventMoveBlock`
+
+```ts
+interface IMoveBlockEventParam {
+    readonly x: number;
+    readonly y: number;
+    readonly steps: readonly ObjectMoveStep[];
+    readonly safe?: boolean;
+}
+```
+
+从 `(x, y)` 将静态图块转为动态图块，按 `steps` 完整移动，再转回静态图块。
+`safe` 为 `true` 时使用 `transferToStaticIfSafe`，否则使用
+`transferToStatic`。源图块、动态图块、移动控制器或目标静态图块不可用时安全返回
+`void`；移动控制器的 `onEnd` 和最终转换都必须等待。
+
+### `eventDeleteBlock`
+
+```ts
+interface IDeleteBlockEventParam {
+    readonly x: number;
+    readonly y: number;
+}
+```
+
+删除目标坐标的静态图块，并等待该坐标所有动态图块的删除 Promise。地图、图层或
+坐标不可用时安全返回 `void`。
+
+### `eventMoveHero`
+
+```ts
+interface IMoveHeroEventParam {
+    readonly steps: readonly ObjectMoveStep[];
+}
+```
+
+把完整 `steps` 队列加入 `env.state.hero.location.mover` 并启动一次移动。勇士或
+移动器缺失、移动已在进行中或动作无法启动时安全返回 `void`；启动成功后等待
+`IMoverController.onEnd`。
+
+### `eventMoveHeroStep`
+
+```ts
+interface IMoveHeroStepEventParam {}
+```
+
+不读取额外字段，使用勇士当前移动方向执行一次 `forward(1)`。勇士、移动器或控制器
+缺失时安全返回 `void`，启动成功后等待 `onEnd`。
+
+### `eventTouchFront`
+
+```ts
+interface ITouchFrontEventParam {}
+```
+
+不读取额外字段。以勇士当前位置和当前朝向计算面前一格，收集该坐标的点事件、静态
+图块事件和动态图块事件，以 `EventTrigger.OnTouch` 通过现有事件执行器顺序触发。
+缺少勇士、地图、图层、目标位置或事件执行器时安全返回 `void`；事件执行 Promise
+必须等待。该函数只触发 `onTouch`，不移动勇士。
+
+### `eventInsertEvents`
+
+```ts
+interface IInsertEventsEventParam {
+    readonly ids: readonly string[];
+}
+```
+
+按 `ids` 顺序临时构造事件调用，复用当前 `env`，通过当前事件执行器执行一次；不把
+这些事件写入 `IGameEventStore`，也不改变地图持久化数据。空序列、缺失事件存储、缺失
+事件 id 或缺失执行器时安全跳过；执行 Promise 必须等待。
+
+### `eventInsertEvent`
+
+```ts
+interface IInsertEventEventParam {
+    readonly id: string;
+}
+```
+
+这是 `eventInsertEvents` 的单 id 形式：只临时执行 `id` 对应事件，复用当前 `env`，
+不写入事件存储。空 id、缺失事件、缺失事件存储或缺失执行器时安全返回 `void`，
+执行 Promise 必须等待。
+
+## Registration
+
+`data-state/src/event/index.ts` 提供稳定名称对应的默认注册项，顺序为：
+
+1. `eventSetBlock`
+2. `eventMoveBlock`
+3. `eventDeleteBlock`
+4. `eventMoveHero`
+5. `eventMoveHeroStep`
+6. `eventTouchFront`
+7. `eventInsertEvents`
+8. `eventInsertEvent`
+
+`CoreState` 在创建 `GameEventSystem` 时传入该注册项集合；`GameEventSystem` 将其
+转换为 AnonTokyo 的 built-in function entries。除这八项外，本阶段不注册任何
+legacy built-in。