From 848f9b63280230c397989dcb12a9f96ae9e10a0c Mon Sep 17 00:00:00 2001
From: unanmed <1319491857@qq.com>
Date: Thu, 10 Sep 2026 12:55:39 +0800
Subject: [PATCH] docs(03): record confirmed integration contracts

---
 .planning/phases/03-data-completion/03-CONTEXT.md   |  8 ++++++++
 .../phases/03-data-completion/03-DISCUSSION-LOG.md  | 13 +++++++++++++
 2 files changed, 21 insertions(+)

diff --git a/.planning/phases/03-data-completion/03-CONTEXT.md b/.planning/phases/03-data-completion/03-CONTEXT.md
index 74187de..365a76d 100644
--- a/.planning/phases/03-data-completion/03-CONTEXT.md
+++ b/.planning/phases/03-data-completion/03-CONTEXT.md
@@ -39,6 +39,11 @@
 - **D-15:** 提供专用 Node 验证命令，直接创建顶层实例、加载录像并在失败时返回非零状态；它与数据端单测门禁分开执行。
 - **D-16:** `data-common`、`data-base`、`data-system`、`data-state` 四层的 TypeScript 错误全部清零，并针对这四层检查循环引用。渲染端或 legacy-only 的无关问题不扩大为本阶段范围。
 - **D-17:** 本阶段系统级任务较多，遇到任何接口语义、系统边界、依赖关系或实现路径上的不确定问题，都必须暂停并提问确认，不得擅自选择“看起来合理”的方案绕过问题。
+- **D-18:** 顶层工厂采用 `createCoreState(options?)` 作为主入口；Node 使用内存存档适配器，从固定初始状态 reset，并比较关键状态快照。
+- **D-19:** legacy converter 和数据源通过集中依赖对象注入，`CoreState` 不直接读取 legacy 全局。
+- **D-20:** 循环依赖门禁覆盖四个数据包内部及其相互边界，允许依赖无环的 `@motajs/common` 基础包。
+- **D-21:** 新增专用 `pnpm test:data-node` 命令，使用 `script/test-data-node.ts` 或等价 Node runner，固定 fixture 放在 `packages-user/data-state/test/fixtures/`。
+- **D-22:** Tile 以工作区当前用户接口为准：`ITileRawData.events` 保存默认事件映射，`ITileStore.getEvent(num)` 返回事件映射；旧的 `trigger` 标量实现必须迁移到此契约。
 
 ### the agent's Discretion
 没有授权 AI 在接口语义或系统边界上自行决策的事项。
@@ -66,6 +71,7 @@
 - `packages-user/data-common/src/replay/system.ts` — replay command registration and route recording implementation
 - `packages-user/data-common/src/replay/sandbox.ts` — sequential replay execution and failure behavior
 - `packages-user/data-common/src/replay/func.ts` — existing replay safety decorators
+- `packages-user/data-common/src/store/types.ts` — current user-authored Tile raw-data and event accessor contract
 - `packages-user/data-system/src/event/system.ts` — event interpreter and built-in function registration point
 - `packages-user/data-system/src/event/executor.ts` — event invocation and reduction behavior
 - `packages-user/data-state/src/core.ts` — current top-level four-layer construction and legacy initialization path
@@ -89,6 +95,7 @@
 - Data-side code must remain DOM-free. Rendering communication is gated through `r()`/`rf()` or hooks.
 - `pnpm test:ci` is the existing deterministic non-watch test command; Phase 3 needs a dedicated Node replay command in addition to the data-side test gate.
 - The current top-level path still exports `state = new CoreState()` and uses legacy globals for initial data loading, so factory creation and injectable legacy conversion require careful compatibility handling.
+- The workspace now contains a user adjustment to `ITileRawData.events` and `ITileStore.getEvent()`; implementation must follow that contract rather than restore the previous `trigger` shape.
 
 ### Integration Points
 - `packages-user/data-state/src/core.ts` is the top-level orchestration point for system construction, default registration, saveable content, replay commands, and event built-ins.
@@ -115,6 +122,7 @@
 - Full legacy system removal and migration belongs to Phase 5.
 - Full mobile/desktop rendering integration belongs to Phase 4.
 - A complete legacy event built-in catalog remains deferred until its interfaces and scope are explicitly decided; Phase 3 registers only the minimum closed-loop set.
+- Exact factory option fields, replay fixture actions, event built-in names/signatures, and snapshot field list remain user-owned details that must be confirmed before implementation if the planner cannot derive them without guessing.
 
 </deferred>
 
diff --git a/.planning/phases/03-data-completion/03-DISCUSSION-LOG.md b/.planning/phases/03-data-completion/03-DISCUSSION-LOG.md
index 33051e7..e6a6afe 100644
--- a/.planning/phases/03-data-completion/03-DISCUSSION-LOG.md
+++ b/.planning/phases/03-data-completion/03-DISCUSSION-LOG.md
@@ -63,6 +63,19 @@
 **User's choice:** 使用固定端到端录像和精确状态快照，专用 Node 命令失败返回非零；四个数据层包的类型错误与循环引用全部清零。
 **Notes:** 最终录像应覆盖顶层初始化、玩家动作、事件或状态变化和正常结束，并承担 Phase 1 验证目标。
 
+### Follow-up decisions
+
+| Decision | Selected |
+|----------|----------|
+| Node 存档 | 内存适配器；从固定初始状态 reset，并比较关键状态快照 ✓ |
+| Legacy 注入 | 通过集中依赖对象注入 converter/data source，CoreState 不读取 legacy 全局 ✓ |
+| 循环门禁 | 四个 data 包内部及其边界；允许无环的 `@motajs/common` 基础依赖 ✓ |
+| Node 命令 | `pnpm test:data-node`，使用 `script/test-data-node.ts` 或等价 runner，fixture 位于 `packages-user/data-state/test/fixtures/` ✓ |
+
+### Tile contract clarification
+
+用户已调整工作区接口设计，规划以当前 `packages-user/data-common/src/store/types.ts` 为准：`ITileRawData.events` 保存默认事件映射，`ITileStore.getEvent(num)` 返回事件映射。旧的 `trigger` 标量实现不再是候选契约。
+
 ---
 
 ## the agent's Discretion