sindoring
5b10288ff7
Work-Package: M03-RND-STREAMING-PLANNER-001 Agent: sindo-main-codex Tests: planner and repository gates pass Fidelity: no renderer policy or visual change
119 lines
5.3 KiB
Markdown
119 lines
5.3 KiB
Markdown
# M03-RND-STREAMING-PLANNER-001 — Pure streaming target planner
|
|
|
|
<!-- OPENWC_CLAIM:M03-RND-STREAMING-PLANNER-001:sindo-main-codex:2026-07-17 -->
|
|
|
|
## Ownership
|
|
|
|
- Target: M03
|
|
- Program: RND
|
|
- Owner/Agent ID: sindo-main-codex
|
|
- Branch: `work/sindo-main-codex/m03-streaming-target-planner`
|
|
- Lease expires UTC: 2026-07-17
|
|
- Integrator: M03 milestone integrator
|
|
|
|
## Outcome
|
|
|
|
Extract runtime/editor ADT wanted/retained-set calculation and boundary prefetch
|
|
selection from `StreamingWorldLoader` into a scene-free, deterministic
|
|
`StreamingTargetPlanner` with typed focus input and asset-free contract tests.
|
|
|
|
## Non-goals
|
|
|
|
- Change load/retain radii, boundary thresholds, queue priority or LOD policy.
|
|
- Move queue mutation, async jobs, cache ownership or GPU finalization.
|
|
- Extract `RenderBudgetScheduler` or asset services in this package.
|
|
- Change cache formats, renderer profiles or target milestone status.
|
|
|
|
## Paths
|
|
|
|
- Exclusive: `src/render/streaming/streaming_target_planner.gd`,
|
|
`src/render/streaming/streaming_target_policy.gd`,
|
|
`src/render/streaming/streaming_target_plan.gd`,
|
|
`src/tools/verify_streaming_target_planner.gd`,
|
|
`docs/modules/streaming-target-planner.md`, this claim
|
|
- Shared/hotspots: `src/scenes/streaming/streaming_world_loader.gd`,
|
|
`src/tools/verify_coordinate_conversion_boundaries.gd`,
|
|
`docs/modules/world-renderer.md`, `docs/modules/coordinate-mapping.md`,
|
|
`docs/modules/README.md`, `RENDER.md`
|
|
- Generated/ignored: `.godot`, native DLL, generated cache resources and
|
|
proprietary renderer corpus
|
|
|
|
## Contracts and data
|
|
|
|
- Input: immutable `GodotWorldPosition`, available-tile key set and immutable
|
|
`StreamingTargetPolicy`
|
|
- Output: immutable `StreamingTargetPlan` with focus tile plus detached
|
|
wanted/retained tile-key sets
|
|
- Tile-key representation remains the streamer's existing `<x>_<y>` internal key
|
|
- Schema/cache/coordinate versions: unchanged
|
|
- Consumers: `StreamingWorldLoader` runtime/editor refresh paths
|
|
|
|
## Dependencies
|
|
|
|
- Requires: M01 typed coordinates/focus and integrated facade package `a100ced`
|
|
- Blocks: budget scheduler extraction and planner performance regression gate
|
|
- External state: none; tests use synthetic tile catalogs
|
|
|
|
## Verification
|
|
|
|
- Commands: dedicated planner verifier, facade/focus/coordinate regressions,
|
|
renderer manifest/dry-run and repository gates
|
|
- Fixtures: center, edge, corner, unavailable-tile, clamped-radius and editor cases
|
|
- Fidelity evidence: expected tile sets are captured from current formulas; full
|
|
renderer dry-run retains all seven checkpoint plans
|
|
- Performance budget: planner work remains bounded by square radii and creates no
|
|
Node, Resource, task, cache or RID
|
|
|
|
## Documentation deliverables
|
|
|
|
- Inline API docs for planner/policy/plan
|
|
- New module specification with input/output table and data-flow diagram
|
|
- Updated world-renderer data-flow/sequence/ownership/source map
|
|
- Updated module registry and renderer notes
|
|
|
|
## Simplicity and naming
|
|
|
|
- Important names: `StreamingTargetPlanner`, `StreamingTargetPolicy`,
|
|
`StreamingTargetPlan`
|
|
- Simplest approach: one pure calculator plus two immutable value objects
|
|
- Rejected complexity: generic graph planner, priority framework, service
|
|
container, job ownership or duplicate available-tile catalog
|
|
- Unavoidable complexity: boundary-prefetch cross product must preserve corner
|
|
behavior and existing string tile keys
|
|
- Measured optimization evidence: no new optimization; exact extraction
|
|
|
|
## Status
|
|
|
|
- State: ready-for-review
|
|
- Done: extracted immutable policy/plan and pure planner, migrated runtime/editor
|
|
target refresh, added behavior/dependency/performance coverage and module docs
|
|
- Next: M03 integrator reviews and merges `e887c3b`
|
|
- Blocked by:
|
|
|
|
<!-- OPENWC_HANDOFF:READY:M03-RND-STREAMING-PLANNER-001:e887c3b -->
|
|
|
|
## Handoff
|
|
|
|
- Commit: `e887c3b`
|
|
- Results: runtime/editor wanted and retained ADT sets plus boundary-prefetch
|
|
centers are calculated by scene-free `StreamingTargetPlanner`; streamer keeps
|
|
queue ordering, LOD/detail state, jobs, caches, nodes and RIDs.
|
|
- Verification: planner `cases=5 iterations=250 average_ms=1.765`; facade
|
|
`delegation=3 runtime_scenes=2 tools=3`; focus `contract=1 runtime_scenes=2
|
|
capture_tools=3`; coordinate boundary `files=109 consumers=6`; renderer
|
|
manifest `checkpoints=7 coverage=7 caches=7`; shutdown ownership passed;
|
|
documentation, coordination and diff gates passed.
|
|
- Fidelity: center/corner/catalog/clamp/editor fixtures preserve the extracted
|
|
formulas; seven-checkpoint dry-run retained all plans. No radius, threshold,
|
|
load priority, cache version, placement, material, animation or visibility
|
|
rule changed. No build-12340 parity claim is added.
|
|
- External/local inputs: ignored native DLL and generated ADT resource scripts
|
|
were copied from master for worktree smoke only. Proprietary ADT and character
|
|
assets were unavailable, so the dry-run emitted expected degraded-data diagnostics.
|
|
- Remaining risks: exact p95/p99 impact still needs an asset-backed baseline;
|
|
pathological custom radii are not benchmarked; tile-key strings remain the
|
|
existing internal catalog representation; queue/LOD application remains monolithic.
|
|
- Documentation updated: new planner module spec with API/input/output/data-flow/
|
|
sequence/ownership/recovery/performance/source-map sections; world renderer,
|
|
coordinate mapping, module registry and renderer implementation notes updated.
|