open-wc/docs/modules/wmo-render-resource-finalizer.md

WMO Render Resource Finalizer

Metadata

Field	Value
Status	Implemented extraction
Target/work package	M03 / M03-RND-WMO-RENDER-RESOURCE-FINALIZER-001
Owners	Lightweight WMO terminal status polling, Resource validation and cache/missing publication
Last verified	Worktree work/sindo-main-codex/m03-wmo-render-resource-finalizer, 2026-07-18
Profiles/capabilities	Profile-independent lightweight WMO render-cache finalization

Purpose

Finalize pending lightweight WMO .res cache requests outside StreamingWorldLoader: poll terminal status, retrieve a loaded Resource, enforce exact script/current-format validation and publish either the exact Resource or the historical missing outcome.

Non-goals

• Select normalized WMO/cache paths or start threaded requests.
• Finalize cached WMO PackedScenes or live WMOBuilder prototypes.
• Own cache lifetime, placements, build queues, scheduler permits or Nodes.
• Change WMOStreamingResource.FORMAT_VERSION, fallback or visible behavior.

Context and boundaries

flowchart LR
    Loader[StreamingWorldLoader] -->|compose and tick| Finalizer[WmoRenderResourceFinalizer]
    Cache[WmoRenderResourceCacheState] -->|pending snapshot| Finalizer
    Finalizer --> ResourceLoader
    Finalizer -->|validated Resource or missing| Cache
    Cache --> Build[WMO render build queue]

The service may depend on ResourceLoader, the injected expected Script and the render Resource cache-state API. File selection, FileAccess, SceneTree, WMOBuilder, placement, scheduler and application layers remain outside it.

Public API

Symbol	Kind	Purpose	Thread/lifetime	Errors
poll_terminal_requests(cache_state)	Command/query	Poll all pending paths once and publish terminal outcomes	Renderer main thread; stateless between calls	Null state returns zero; non-terminal retained
is_current_render_resource(resource)	Query	Enforce exact injected Script and minimum format	Renderer main thread; stateless	Null/wrong/stale false
load_threaded_get_status(path)	Boundary query	Read opaque threaded status	Renderer main thread; injectable in tests	ResourceLoader semantics
load_threaded_get(path)	Boundary query	Retrieve terminal Resource	Renderer main thread; injectable in tests	Null accepted as failed outcome

Inputs and outputs

Direction	Contract/data	Producer	Consumer	Ownership	Thread/lifetime
Input	Detached normalized-path to .res path Dictionary	Render cache state	Finalizer polling	Caller-owned copy	One poll pass
Input	Opaque ResourceLoader status	ResourceLoader	Finalizer	Integer value	One path poll
Input	Terminal Resource	ResourceLoader	Validator	Borrowed reference	One completion
Input	Expected Script/minimum format	Loader composition	Validator	Borrowed/value	Finalizer lifetime
Output	Exact validated Resource	Finalizer	Render cache state	Cache adopts strong reference	Until full clear
Output	Missing transition	Finalizer	Render cache state	Path-only state	Until transient clear

Data flow

flowchart TD
    Snapshot[Detached pending snapshot] --> Next[Next path in insertion order]
    Next --> Poll[Poll ResourceLoader status]
    Poll --> Terminal{Loaded or failed?}
    Terminal -->|no| Retain[Retain pending]
    Terminal -->|failed| Missing[Complete as missing]
    Terminal -->|loaded| Get[Get terminal Resource]
    Get --> Validate{Exact script and format current?}
    Validate -->|yes| Adopt[Complete with exact Resource]
    Validate -->|no| Missing
    Retain --> Next
    Adopt --> Next
    Missing --> Next

Lifecycle/state

stateDiagram-v2
    [*] --> Polling
    Polling --> Pending: non-terminal status
    Polling --> Missing: failed/null/wrong/stale
    Polling --> Cached: exact script and current format
    Pending --> Polling: later tick
    Missing --> [*]
    Cached --> [*]

The finalizer retains no per-path state. The sibling cache state owns all Pending/Cached/Missing lifetime and reset transitions.

Main sequence

sequenceDiagram
    participant Loader as StreamingWorldLoader
    participant Finalizer as WmoRenderResourceFinalizer
    participant Cache as WmoRenderResourceCacheState
    participant RL as ResourceLoader
    Loader->>Finalizer: poll_terminal_requests(Cache)
    Finalizer->>Cache: request_paths_snapshot()
    loop insertion-ordered paths
        Finalizer->>RL: load_threaded_get_status(cache path)
        alt non-terminal
            Finalizer->>Finalizer: retain request
        else failed
            Finalizer->>Cache: complete_request_as_missing(path)
        else loaded
            Finalizer->>RL: load_threaded_get(cache path)
            Finalizer->>Finalizer: exact Script and format validation
            Finalizer->>Cache: complete with Resource or missing
        end
    end

Dependency diagram

flowchart TB
    Loader[StreamingWorldLoader] --> Finalizer[WmoRenderResourceFinalizer]
    Loader --> Cache[WmoRenderResourceCacheState]
    Finalizer --> Cache
    Finalizer --> ResourceLoader
    Finalizer --> Script[WMOStreamingResource Script contract]
    Finalizer -. no dependency .-> FileAccess
    Finalizer -. no dependency .-> WMOBuilder
    Finalizer -. no dependency .-> Node
    Finalizer -. no dependency .-> Scheduler

Ownership, threading and resources

• Renderer main thread serializes polling and cache-state publication.
• Finalizer owns no Resource, request, Node, RID or file lifetime.
• Cache state adopts accepted exact Resource references until its full clear.
• Loader owns request admission, fallback/build orchestration and shutdown order.
• Detached snapshots allow terminal cache-state mutation during iteration.

Errors, cancellation and recovery

Failure/state	Detection	Behavior	Diagnostic	Recovery
Null cache state	Guard	Return zero	Contract verifier	Correct composition
Non-terminal request	Status	Retain pending	Pending count	Poll next tick
Failed request	Terminal status	Complete missing	Negative cache	Transient reset/rebuilt cache
Null/wrong-script Resource	Validation	Complete missing	Synthetic fixture	Rebuild cache and reset
Stale format	Format below injected minimum	Complete missing	Synthetic fixture	Rebuild cache and reset
Shutdown	Loader lifecycle	Drain then cache clear	Shutdown verifier	New loader starts absent

Configuration and capabilities

The loader injects the exact WMOStreamingResource Script and its FORMAT_VERSION. The service introduces no setting, profile, permit or cache format. WMO cache paths and build budgets remain loader-owned.

Persistence, cache and migration

The module serializes nothing and changes no cache format. It only enforces the existing script identity and current-or-newer format rule before runtime cache adoption, so no migration or rebake is introduced.

Diagnostics and observability

• poll_terminal_requests returns terminal completion count for tests/future metrics.
• Existing cache pending count and renderer wmobuild metrics are unchanged.
• The service emits no logs; normalized relative path remains the correlation key.

Verification

• verify_wmo_render_resource_finalizer.gd: null/non-terminal, insertion order, failed/load boundary, null/wrong/stale rejection, current/newer identity, source ownership and 1,000 terminal polls under one second.
• Cache-state, WMO queue/planner/registry/resolver, shutdown, facade, internal-access and baseline regressions protect adjacent behavior.
• Fidelity evidence is exact orchestration extraction; no asset-backed visual or original-client parity claim is made.

Extension points

• A legal current/stale .res fixture can extend validation evidence unchanged.
• PackedScene finalization remains separate because it instantiates a probe Node and uses WMOBuilder metadata rather than script/format Resource fields.

Capability status

Capability	Status	Evidence	Gap/next step
Lightweight WMO terminal polling	Implemented extraction	Status/order/source/timing verifier	Asset-backed traversal pending
Script/format validation	Implemented extraction	Wrong/stale/current/newer fixtures	Legal serialized fixture pending
Resource/missing publication	Implemented extraction	Exact identity/negative-state fixtures	Asset-backed lifetime/leak run pending
WMO materialization	Loader-owned	Existing build regressions	Further safe extraction pending

Known gaps and risks

• ResourceLoader status/get remains synchronous main-thread boundary polling.
• No proprietary WMO corpus, serialized corrupt-version fixture, leak run, traversal p95/p99 or paired original-client capture is included.

Source map

Path	Responsibility
src/render/wmo/wmo_render_resource_finalizer.gd	Terminal polling, validation and publication
src/render/wmo/wmo_render_resource_cache_state.gd	Resource/missing/request ownership and resets
src/scenes/streaming/streaming_world_loader.gd	Composition, request admission, fallback and build orchestration
src/resources/wmo_streaming_resource.gd	Serialized cache contract and format version
src/tools/verify_wmo_render_resource_finalizer.gd	Terminal-I/O/validation/source/timing regression

Related decisions and references

• wmo-render-resource-cache-state.md
• wmo-render-build-queue.md
• world-renderer.md
• ../../RENDER.md
• ../../targets/roadmap/02-rendering-and-graphics.md