sindoring
9c3f7018fb
Work-Package: M03-RND-FACADE-001 Agent: sindo-main-codex Tests: post-merge verification follows Fidelity: no runtime change
118 lines
5.1 KiB
Markdown
118 lines
5.1 KiB
Markdown
# M03-RND-FACADE-001 — Renderer facade first seam
|
|
|
|
<!-- OPENWC_CLAIM:M03-RND-FACADE-001:sindo-main-codex:2026-07-17 -->
|
|
|
|
## Ownership
|
|
|
|
- Target: M03
|
|
- Program: RND
|
|
- Owner/Agent ID: sindo-main-codex
|
|
- Branch: `work/sindo-main-codex/m03-renderer-facade`
|
|
- Lease expires UTC: 2026-07-17
|
|
- Integrator: M03 milestone integrator
|
|
|
|
## Outcome
|
|
|
|
Introduce `WorldRenderFacade` as the only runtime/tool caller surface for typed
|
|
streaming focus updates and read-only renderer metrics, while retaining
|
|
`StreamingWorldLoader` as the unchanged internal implementation.
|
|
|
|
## Non-goals
|
|
|
|
- Extract the pure target planner or budget scheduler in this package.
|
|
- Add environment or entity-presentation commands before their contracts exist.
|
|
- Replace the M02 `TerrainQuery` gameplay boundary in this package.
|
|
- Change streaming radii, queues, cache formats, visuals or quality presets.
|
|
- Mark M03 complete or edit its checklist/Evidence.
|
|
|
|
## Paths
|
|
|
|
- Exclusive: `src/render/world_render_facade.gd`,
|
|
`src/tools/verify_world_render_facade.gd`, this claim
|
|
- Shared/hotspots: both runtime streaming scenes, three renderer capture/probe
|
|
tools, `src/tools/verify_streaming_focus.gd`, `docs/modules/world-renderer.md`,
|
|
`docs/modules/README.md`, `RENDER.md`
|
|
- Generated/ignored: local `.godot`, native build outputs, caches and proprietary
|
|
renderer corpus
|
|
|
|
## Contracts and data
|
|
|
|
- Public API: `set_streaming_focus`, `refresh_streaming_focus`,
|
|
`renderer_metrics_snapshot`
|
|
- Scene adapter: explicit `streaming_focus_source_path` owned by the facade
|
|
- Internal implementation seam: `streaming_world_loader_path`; callers must not
|
|
read streamer queues or call its methods directly
|
|
- Schema/cache/coordinate contracts: unchanged
|
|
- Consumers: runtime scenes, capture tool and renderer probes
|
|
|
|
## Dependencies
|
|
|
|
- Requires: M01 `StreamingFocus` and merged M02 closeout on master `4f566b1`
|
|
- Blocks: environment/entity/ground facade contracts and planner extraction
|
|
- External state: none; contract verification uses a test double
|
|
|
|
## Verification
|
|
|
|
- Commands: dedicated facade verifier, streaming-focus regression, renderer
|
|
baseline manifest/dry-run, coordinate boundary and repository gates
|
|
- Fixtures: typed focus, source Node3D and read-only metrics test double
|
|
- Fidelity evidence: no renderer configuration, planner, queue, placement,
|
|
visibility, material, animation or cache behavior changes
|
|
- Performance budget: one source position sample per process frame; target
|
|
recomputation remains throttled inside the existing streamer
|
|
|
|
## Documentation deliverables
|
|
|
|
- Inline public API docs for facade properties and methods
|
|
- Updated world-renderer module specification
|
|
- Updated data-flow, sequence and dependency diagrams
|
|
- Updated source map/status and renderer notes
|
|
|
|
## Simplicity and naming
|
|
|
|
- Important names: `WorldRenderFacade`, `renderer_metrics_snapshot`
|
|
- Simplest approach: one small Node adapter delegating to the existing streamer
|
|
- Rejected complexity: service container, generic command bus, streamer rewrite
|
|
or duplicate queue/cache state
|
|
- Unavoidable complexity: scene-relative source and implementation paths are
|
|
resolved on the main thread with explicit diagnostics
|
|
- Measured optimization evidence: not applicable; behavior-preserving seam
|
|
|
|
## Status
|
|
|
|
- State: ready-for-review
|
|
- Done: introduced the facade, migrated two runtime scenes and three renderer
|
|
tools, added regression coverage and updated renderer documentation
|
|
- Next: M03 integrator reviews and merges `3d528e3`
|
|
- Blocked by:
|
|
|
|
<!-- OPENWC_HANDOFF:READY:M03-RND-FACADE-001:3d528e3 -->
|
|
<!-- OPENWC_INTEGRATION:ACCEPTED:M03-RND-FACADE-001:a100ced -->
|
|
|
|
## Handoff
|
|
|
|
- Commit: `3d528e3`
|
|
- Integration: accepted in master merge `a100ced`
|
|
- Results: `WorldRenderFacade` is the runtime/tool surface for typed focus and
|
|
detached metrics; the existing streamer remains the sole owner of queues,
|
|
caches, tasks, nodes and RIDs.
|
|
- Verification: facade `delegation=3 runtime_scenes=2 tools=3`; streaming focus
|
|
`contract=1 runtime_scenes=2 capture_tools=3`; coordinate boundary
|
|
`files=105 native_boundary=1 oracle=1 consumers=5 classifier_cases=6`;
|
|
render manifest `checkpoints=7 coverage=7 caches=7`; seven-checkpoint headless
|
|
dry-run; coordination/documentation/diff gates passed.
|
|
- Fidelity: no changes to renderer target calculation, budgets, queue order,
|
|
cache versions, placement, visibility, materials or animation. The dry-run
|
|
retained all seven checkpoint plans. No build-12340 parity claim is added.
|
|
- External/local inputs: ignored native DLL and generated ADT resource scripts
|
|
were copied from master only to run the worktree smoke. Proprietary extracted
|
|
ADT and character GLB data were unavailable, producing the expected dry-run
|
|
degraded-data diagnostics.
|
|
- Remaining risks: environment, entity visuals and ground query are not yet
|
|
facade contracts; streamer exported configuration remains transitional scene
|
|
composition; focus-source sampling adds one small main-thread adapter step per
|
|
process frame while target refresh remains streamer-throttled.
|
|
- Documentation updated: inline facade API, `docs/modules/world-renderer.md`
|
|
public API/inputs/outputs/data-flow/sequence/ownership/recovery/status/source
|
|
map, and `RENDER.md` file map plus implementation note.
|