EPIC-1 Engine Foundation

[learncold]

Summary

ECS 코어와 런타임 파운데이션을 완성한다. 상위 레이어가 domain/application 설계를 쌓을 수 있도록, engine은 범용 ECS 저장소, 시스템 실행 루프, lifecycle, 결정론, world access boundary를 제공한다.

Area

Engine

Target Sprint

Sprint 1

Why Needed

프로젝트 구조상 engine -> domain -> application 계층의 바닥을 먼저 안정화해야 이후 군중 시뮬레이션 로직이 특정 UI나 ad hoc runtime 규칙에 묶이지 않는다. engine foundation은 domain이 crowd movement, routing, metrics를 시스템 단위로 올릴 수 있는 최소 공통 계약을 제공해야 한다.

Goal / Outcome

EngineRuntime, EngineWorld, SystemScheduler, deterministic seed, lifecycle reset, observer boundary가 정리된 공통 foundation을 만들고, no-app test 경로에서 안정적으로 검증 가능한 상태를 만든다.

In Scope

• ECS 읽기/query와 deferred mutation 기본 API
• system registration 및 phase 기반 실행 루프
• runtime-owned resources와 deterministic seed 계약
• lifecycle reset과 repeatable run 기반 정리
• engine public observer boundary 및 통합 smoke test

Out of Scope

• domain crowd logic 구현
• Qt UI 및 renderer 구현
• scenario/result artifact 설계

Child Tasks

• Task-Implement WorldQuery facade for ECS reads #9 WorldQuery ECS 읽기 facade ✅
• Task-Implement deferred WorldCommands and CommandBuffer #10 CommandBuffer / WorldCommands deferred mutation ✅
• Task-Implement EngineSystem contract and FrameClock #11 EngineSystem 추상 인터페이스 ✅
• Task-Implement EngineRuntime minimal orchestration API #12 EngineRuntime 최소 오케스트레이터
• Task-Implement SystemScheduler phase ordering and execution loop #47 SystemScheduler phase 기반 실행 루프
• Task-Implement ResourceStore and WorldResources for shared simulation state #21 ResourceStore / WorldResources 공유 상태 저장소
• Task-Implement DeterministicRng and run seed contract #22 DeterministicRng run seed 계약 정리
• Task-Add engine smoke test for query and deferred mutation flow #13 engine 통합 smoke test
• Task-Define runtime observer boundary for post-frame synchronization #92 post-frame synchronization용 runtime observer boundary
• Task-WorldQuery 직접 생성 패턴을 EngineWorld 경유로 일원화 #93 EngineWorld 기준 query 접근 경계 일원화
• Task-EngineStepContext에 fixedDeltaTime 추가 #94 multi-phase EngineRuntime loop 구현
• Task-TriggerPolicy 실행 조건과 Interval cadence 적용 #95 TriggerPolicy 실행 조건과 Interval cadence 적용
• Task-stop/reinitialize 경계의 runtime-owned state reset contract 확장 #96 stop/reinitialize 시 engine-owned state reset 전략 구현

Architecture / Dependency Notes

• engine은 domain/application 타입을 include하지 않는다.
• runtime public contract는 EngineWorld, EngineStepContext, scheduler descriptor 수준에서 고정한다.
• lifecycle, resource, rng, observer 같은 cross-cutting 상태는 engine 내부 소유로 정리한다.
• 후속 domain system은 engine phase/trigger 규칙 위에만 쌓이고, engine에 domain semantics를 밀어넣지 않는다.

Done Criteria

• child task가 모두 현재 설계 용어로 정렬된다.
• ctest --preset test-no-app-debug가 통과한다.
• engine foundation이 domain/application 의존 없이 반복 실행과 테스트가 가능한 상태가 된다.

Related Docs

• docs/architecture/프로젝트 구조.md
• docs/product/Product Backlog.md
• uml/engine-ecs-core.puml
• uml/engine-overview.puml
• uml/engine-runtime-core.puml
• uml/project-structure.puml

Repository Checks

• I checked the current GitHub Project board before creating or updating this epic.
• I will keep the issue title aligned with the repository naming convention.