From 19df30e9e1c375ba415707404d2106a6e36e0fd3 Mon Sep 17 00:00:00 2001 From: unanmed <1319491857@qq.com> Date: Thu, 10 Sep 2026 20:23:03 +0800 Subject: [PATCH] docs(03-07): complete serialized event loading gap closure plan --- .planning/WINDOWS.md | 18 +- .../03-data-completion/03-07-SUMMARY.md | 178 ++++++++++++++++++ 2 files changed, 187 insertions(+), 9 deletions(-) create mode 100644 .planning/phases/03-data-completion/03-07-SUMMARY.md diff --git a/.planning/WINDOWS.md b/.planning/WINDOWS.md index 822bb0e..16d78d3 100644 --- a/.planning/WINDOWS.md +++ b/.planning/WINDOWS.md @@ -1,10 +1,10 @@ --- schema_version: 1 -open_count: 14 +open_count: 12 waived_count: 0 -fixed_count: 3 +fixed_count: 5 total_count: 17 -last_updated: 2026-09-10T09:18:59.589Z +last_updated: 2026-09-10T12:20:54.566Z --- # Broken Windows Ledger @@ -15,7 +15,7 @@ last_updated: 2026-09-10T09:18:59.589Z | id | phase | kind | file | line | description | status | reason | recorded_at | resolved_at | |----|-------|------|------|------|-------------|--------|--------|-------------|-------------| -| 1 | 01 | stub | packages-user/data-state/src/core.ts | 153 | Serialized event registration and map-id binding remains an intentional deferred TODO. | open | | 2026-09-08T15:06:40.634Z | | +| 1 | 01 | stub | packages-user/data-state/src/core.ts | 153 | Serialized event registration and map-id binding remains an intentional deferred TODO. | fixed | | 2026-09-08T15:06:40.634Z | 2026-09-10T12:20:52.319Z | | 2 | 01 | unrun-verify | .planning/phases/01-event/01-05-SUMMARY.md | | Downstream implementation verification was not run because the user explicitly prohibited downstream plan execution. | open | | 2026-09-08T15:37:54.227Z | | | 3 | 01 | deviation | packages-user/data-base/src/map/mapLayer.ts | | Replaced unsupported Map upsert runtime calls so the raw map event path runs under Node Vitest. | open | | 2026-09-08T15:54:23.173Z | | | 4 | 02 | skipped-test | packages-user/data-common/src/common/mover.test.ts | | 4 个 it.skip 坐标回写回归用例（x/y 正交、斜向、传送），待 02-02 修复 mover.ts:651 后翻绿 | fixed | | 2026-09-09T07:51:25.555Z | 2026-09-09T09:34:39.843Z | @@ -28,7 +28,7 @@ last_updated: 2026-09-10T09:18:59.589Z | 11 | 03 | unrun-verify | .planning/phases/03-data-completion/deferred-items.md | | Repository type gate remains non-zero on pre-existing render/legacy and Tile contract diagnostics; owned Node tracer and data tests pass. | fixed | | 2026-09-10T07:45:45.249Z | 2026-09-10T07:58:56.466Z | | 12 | 03 | unrun-verify | .planning/phases/03-data-completion/deferred-items.md | | Repository type gate remains non-zero on pre-existing render/legacy diagnostics; Tile contract diagnostics are resolved. | open | | 2026-09-10T07:58:50.208Z | | | 13 | 03 | deviation | packages-user/data-common/src/store/tileStore.test.ts | | Applied ESLint/Prettier CRLF formatting required by the project after functional Tile tests passed. | open | | 2026-09-10T07:59:02.467Z | | -| 14 | 03 | stub | packages-user/data-state/src/core.ts | 166 | Existing deferred serialized event registration and map-event-id binding TODO; preserved by Plan 03-03. | open | | 2026-09-10T08:47:49.808Z | | +| 14 | 03 | stub | packages-user/data-state/src/core.ts | 166 | Existing deferred serialized event registration and map-event-id binding TODO; preserved by Plan 03-03. | fixed | | 2026-09-10T08:47:49.808Z | 2026-09-10T12:20:54.566Z | | 15 | 03 | deviation | packages-user/data-common/src/replay/array.ts | | Repaired replay parameter encoding so diagnostic params remain original and deterministic. | open | | 2026-09-10T09:18:58.279Z | | | 16 | 03 | deviation | packages-user/data-state/test/replayVerifier.ts | | Added a package-local verifier harness shared by Vitest and the Node runner to avoid composite-script import resolution. | open | | 2026-09-10T09:18:58.946Z | | | 17 | 03 | deviation | packages-user/data-state/test/fixtures/closed-loop.ts | | Applied repository Prettier/CRLF formatting to the fixed replay fixture and runner files. | open | | 2026-09-10T09:18:59.589Z | | @@ -42,10 +42,10 @@ last_updated: 2026-09-10T09:18:59.589Z "file": "packages-user/data-state/src/core.ts", "line": 153, "description": "Serialized event registration and map-id binding remains an intentional deferred TODO.", - "status": "open", + "status": "fixed", "reason": "", "recorded_at": "2026-09-08T15:06:40.634Z", - "resolved_at": null + "resolved_at": "2026-09-10T12:20:52.319Z" }, { "id": 2, @@ -198,10 +198,10 @@ last_updated: 2026-09-10T09:18:59.589Z "file": "packages-user/data-state/src/core.ts", "line": 166, "description": "Existing deferred serialized event registration and map-event-id binding TODO; preserved by Plan 03-03.", - "status": "open", + "status": "fixed", "reason": "", "recorded_at": "2026-09-10T08:47:49.808Z", - "resolved_at": null + "resolved_at": "2026-09-10T12:20:54.566Z" }, { "id": 15, diff --git a/.planning/phases/03-data-completion/03-07-SUMMARY.md b/.planning/phases/03-data-completion/03-07-SUMMARY.md new file mode 100644 index 0000000..edb6eec --- /dev/null +++ b/.planning/phases/03-data-completion/03-07-SUMMARY.md @@ -0,0 +1,178 @@ +--- +phase: 03-data-completion +plan: 07 +subsystem: data-state-events +tags: [serialized-events, map-binding, anon-tokyo, node-replay, vitest] + +requires: + - phase: 03-data-completion + provides: Node-safe CoreState, approved event built-ins, raw map event-id contract, and fixed replay fixture +provides: + - Internal serialized Statement[] event registration through the CoreState data-load boundary + - Raw IMapRawData.events binding through MapState.fromRaw before replay execution + - Production-path Node replay regression coverage for trigger preservation, id binding, awaited mutation, and final snapshots +affects: [03-VERIFICATION, Phase 3 data closure, Phase 4 render adaptation] + +actuals: + tokens: 3508 + tasks: 2 + commits: 3 + plan_head_before: 8f3f5cad7dfb15c9d95636348699e61151f4296a + +tech-stack: + added: [] + patterns: + - Internal symbol-keyed CoreState load seam keeps serialized registration out of the public state contract + - GameEvent instances share the assembled GameEventSystem AnonTokyo interpreter + - Raw map event references are bound only by MapState.fromRaw and remain id-only in map data + +key-files: + created: + - packages-user/data-state/src/legacy/events.ts + - packages-user/data-state/test/coreSerializedEvents.test.ts + modified: + - packages-user/data-state/src/core.ts + - packages-user/data-state/src/legacy/dependencies.ts + - packages-user/data-state/test/fixtures/closed-loop.ts + +key-decisions: + - "Keep serialized loading behind the internal LOAD_SERIALIZED_DATA symbol and outside ICoreState, so no public event-registration API is added." + - "Construct serialized events with the existing GameEventSystem interpreter and preserve the supplied EventTrigger and Statement[] references." + - "Use IMapRawData.events plus MapState.fromRaw for coordinate binding; do not persist event bodies in maps or saves." + +patterns-established: + - "Production replay fixtures must enter through the same internal serialized load seam as CoreState rather than calling eventStore.addEvent directly." + +requirements-completed: [DATA-01] + +coverage: + - id: D1 + description: "CoreState registers validated serialized events before binding raw map event ids." + requirement: DATA-01 + verification: + - kind: unit + ref: "packages-user/data-state/test/coreSerializedEvents.test.ts#registers serialized event data before binding map event ids" + status: pass + - kind: other + ref: "pnpm exec tsx script/check-data-type.ts; pnpm exec tsx script/check-data-circular.ts" + status: pass + human_judgment: false + - id: D2 + description: "The fixed Node fixture uses serialized eventSetBlock statements and raw map coordinate references instead of manual event-store insertion." + requirement: DATA-01 + verification: + - kind: integration + ref: "packages-user/data-state/test/coreSerializedEvents.test.ts#executes the registered event once through the replay path" + status: pass + - kind: other + ref: "pnpm test:data-node" + status: pass + human_judgment: false + - id: D3 + description: "The scoped data regression suite remains green with the exact replay snapshot and existing boundaries preserved." + requirement: DATA-01 + verification: + - kind: other + ref: "pnpm test:ci packages-user/data-common packages-user/data-base packages-user/data-system packages-user/data-state" + status: pass + - kind: other + ref: "focused ESLint, Prettier, Chinese coverage-comment scan" + status: pass + human_judgment: false + +duration: 9min +completed: 2026-09-10 +status: complete +--- + +# Phase 3 Plan 7 Summary + +**Serialized Statement[] events now load through the internal CoreState boundary and drive the fixed Node replay through raw map event-id binding** + +## Performance + +- **Duration:** 9 min +- **Started:** 2026-09-10T12:11:50Z +- **Completed:** 2026-09-10T12:20:54Z +- **Tasks:** 2 +- **Files modified:** 5 + +## Accomplishments + +- Added an internal serialized-event adapter that validates event ids, trigger values, statement containers, and registers real `GameEvent` instances with the assembled interpreter +- Wired serialized registration before raw map construction and routed `IMapRawData.events` through `MapState.fromRaw`, preserving id-only map event storage +- Replaced the fixed fixture's direct `eventStore.addEvent` call with the production load seam and added Chinese-commented regression coverage for registration, binding, one execution, and exact replay state + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: GAP-03-01 serialized event registration and CoreState load-order tracer** - `a111b8d` (feat) +2. **Task 2: GAP-03-01 production-path replay fixture and map-event binding regression** - `1b93deb` (test) + +Additional quality commit: + +3. **Prettier/CRLF normalization for changed serialized-event files** - `4b91a0b` (style) + +**Plan metadata:** pending final metadata commit + +## Files Created/Modified + +- `packages-user/data-state/src/legacy/events.ts` - internal serialized event validation, `GameEvent` construction, trigger preservation, and store registration +- `packages-user/data-state/src/core.ts` - load-order wiring and raw-map initialization through `MapState.fromRaw` +- `packages-user/data-state/src/legacy/dependencies.ts` - internal serialized-load payload and symbol boundary +- `packages-user/data-state/test/fixtures/closed-loop.ts` - fixed replay fixture using serialized `eventSetBlock` and raw coordinate event ids +- `packages-user/data-state/test/coreSerializedEvents.test.ts` - focused production-path registration and replay regression tests + +## Decisions Made + +- Kept the new load seam symbol-keyed and absent from `ICoreState` and the public package barrel +- Reused `GameEvent`, `EventTrigger`, `Statement[]`, `GameEventStore`, and `GameEventSystem.executor.interpreter` rather than introducing a second event model +- Preserved the existing no-argument `createCoreState()` and Node-safe dependency selection + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 3 - Blocking] Applied required CRLF and Prettier formatting** + +- **Found during:** Overall quality-gate checks after Task 2 +- **Issue:** The patch tool left changed files with LF line endings and one formatting layout rejected by the repository ESLint/Prettier checks +- **Fix:** Ran Prettier write on only the five plan-owned files and committed the resulting normalization +- **Files modified:** `packages-user/data-state/src/core.ts`, `packages-user/data-state/src/legacy/dependencies.ts`, `packages-user/data-state/src/legacy/events.ts`, `packages-user/data-state/test/fixtures/closed-loop.ts`, `packages-user/data-state/test/coreSerializedEvents.test.ts` +- **Verification:** Focused ESLint and Prettier checks passed +- **Committed in:** `4b91a0b` + +--- + +**Total deviations:** 1 auto-fixed (Rule 3: 1) +**Impact on plan:** Formatting-only correction; no scope or runtime contract expansion. + +## Known Stubs + +- `packages-user/data-state/src/legacy/dependencies.ts:63` — the pre-existing Node branch intentionally registers no browser loading callback; this is required for the DOM-free Node path and is already recorded in `.planning/WINDOWS.md` as an accepted boundary stub + +## Issues Encountered + +- The scoped type gate reports 27 pre-existing diagnostics outside the four data packages and zero in-scope diagnostics; this remains non-blocking and no changed plan file is implicated +- Vitest and Node replay output includes the repository's existing Browserslist notice and expected data-layer logger diagnostics; all assertions and process gates passed + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness + +- GAP-03-01 is closed: CoreState's internal serialized load path registers events before raw map binding, and the fixed Node replay consumes that path without manual event-store insertion +- Existing Phase 3 scope boundaries remain intact: no public registration API, scalar tile triggers, event-body map persistence, browser globals, or Phase 4–6 behavior were added +- `STATE.md` and `ROADMAP.md` were intentionally not modified per the execution request + +--- +*Phase: 03-data-completion* +*Completed: 2026-09-10* + +## Self-Check: PASSED + +- Summary file exists +- Task commits `a111b8d`, `1b93deb`, and formatting commit `4b91a0b` are present in git history +- Focused regression, scoped data suite, Node replay, type, circular, ESLint, Prettier, and Chinese coverage-comment checks passed