Class PerceptionApi

Predicate: does the viewer's sensorium include modality?

Used by the four physical requires* validators and by SensorMixin.filterMessage for modality-attributed frame reception gating.

Resolve a modality singleton by its canonical name. Throws when not found — every consumer should know which modality it's asking for; a missing modality is a config bug.

Accepts the modality NAME ('vision', 'sound', 'verbal-esp'), NOT the BodyPlan organ key (the sound modality's organ key is 'hearing'). To resolve from an organ key, use modalityByOrganKey.

Resolve a modality singleton by its BodyPlan organ key. Used by sensorium when walking BodyPlan.sensoryPorts.modality strings (which are organ keys, not modality names). Returns null when no modality declares this organ key — a reserved organ in the BodyPlan with no v1 modality is silently dropped from the sensorium rather than throwing.

Compute the viewer's percept at loc for modality. Walks signalAt then perceiveFor. Returns null when the signal is null OR the modality's perceiveFor returns null (the default).

Combined async preload for sense / ESP verb-level validators. Warms anatomy (species + clades + body plan) AND modality singletons in parallel — the two everything-must-be-live concerns the validators' sync body assumes. Validators wire this into their preload hook.

Lazy-load every modality singleton. The substrate is not bootstrap-eager-loaded — modalities follow the same pattern as locomotion modes / species clades: singletons load on first verb-level demand via their validator's async preload hook. After this call, sync modalityByName / modalityByOrganKey lookups resolve.

Tolerant of individual template misses (a fresh DB without the seeds yet, an in-progress migration); each modality's StuffApi.singleton failure logs and the cache simply omits that modality. Sense / ESP validators surface their polite refusal downstream when their modality is missing.

Effective sensorium — the modalities the viewer can perceive.

Walks (a) the viewer's BodyPlan sensoryPorts.modality strings (innate organs) and resolves each to its modality singleton via modalityByOrganKey. Returns the deduped union.

Also includes modalities granted by mixins the viewer composes (or has activated via augment-conferral), via MixinApi.getActiveMixins + _grantsModalities.

Returns [] defensively when:

• the viewer isn't an Organism (test fixtures, debug consoles),
• the Organism has no Species,
• the Species has no BodyPlan,
• the BodyPlan has no sensoryPorts (sessile).

Compute the modality's signal at loc. Dispatch is on the modality singleton's signalAt — vision walks light, smell walks odor, sound walks dB, touch reads ambient temperature. Contact + network modalities (taste, ESP) return null.