Rule
A raster Channel owns the truthful meaning and sampling path of its pixels through the validated, versioned pixel_delivery contract. The client derives one inspection schema from that contract. The Layer Fields panel and sampling scheduler consume that schema. Runtime samplers emit the same normalized field keys, after which generic hover/details presentation and field selection operate on the sampled section. None of these stages may infer capabilities from a renderer name or provider identity.
The normalized fields are stable across raster providers:
the frame, valid_time;
valid_time;
same categorical fields without becoming recolourable scalar data;
valid_time for a forecast frame;
- scalar pixels expose their declared inspection field and, when supplied by
- categorical pixels expose
categoryand, when supplied by the frame, - provider-coloured imagery with an exact
color_interpretationexposes the - ordinary imagery with frame-metadata sampling exposes
observed_at, or - imagery with
sampling.mode=noneexposes no invented value.
Category IDs such as flood are values of the single category field, not separate fields. Human-readable category names are localized by the semantic quantity plus category ID. Unknown, transparent, antialiased, or mixed colours remain unknown instead of being assigned to the nearest class.
Ownership boundary
An exact RGBA-to-category mapping in color_interpretation is decoding metadata for immutable provider imagery. It records what an existing provider colour means; it is not a Layer palette and does not authorize recolouring. Numeric and class-preserving palette presentation remains Layer-owned as described by numeric raster encoding and palettes.
Adding a new inspectable raster contract must extend the shared inspection schema and its tests. A provider-specific conditional in the Fields panel or map inspector is not a valid integration path.
Tile-local inspection
Pointer coordinates are local sampling inputs, never network request keys. All raster hover and Details paths sample an immutable decoded frame or tile. Scalar and categorical imagery reuse the RGBA frame cache; imagery provenance and auxiliary metadata use a bounded immutable inspection cache with shared in-flight loads. Cache identity includes authorization, the complete tile URL, frame, channel, and rendering variant. Session disposal clears decoded data. Missing tiles and failed loads are not cached as permanent NoData. A valid tile may contain explicit NoData pixels, which must remain unknown.
A Channel needing fields not present in its visual pixels declares point_inspection.tile_query_value. The legacy declaration name remains for catalog compatibility, but the new client never falls back to coordinate-based requests. The endpoint returns the provider-neutral raster-inspection-v1 binary contract: bounded dimensions, named numeric planes, optional string dictionaries, and explicit NoData. Sampling uses the actual delivered dimensions, not an assumption that a logical 512-pixel tile contains 512 physical pixels. Providers translate to normalized planes on the server, not in the inspector.
Numeric hover and Details read the same delivered encoding at the same zoom; Details no longer performs a separate precise point request. Precision remains that of the Channel's declared pixel encoding. Frame-metadata-only imagery continues to use its local declared timestamp without inventing per-pixel dates.
For metered imagery, inspection reads existing committed metadata only. It must never acquire provider data, reserve budget, or refresh the catalog. Tile inspection is authorized through the same channel access check before private Storage reads. Successful metadata responses use private browser caching; cache misses return a non-cacheable empty response.
The first uncached tile still requires I/O. Further pointer positions within that tile and switching from hover to Details require no additional request. Eviction or a different authorization/frame/variant starts a new load.
Rollout order for Sentinel-2: deploy the backwards-compatible Edge Function, apply 20260928000001_raster_tile_inspection.sql, then deploy the client. Old clients retain the point endpoint during rollout. The production rollout and SQL verification are separate from local TypeScript tests.
Pointer lifecycle
Mapbox's canvas mouseup does not cover a drag released outside the map. Inspection must also observe window-level release and focus loss, and reconcile button state from incoming mouse movement. A completed drag must not leave hover disabled when the pointer returns. This is independent of raster metadata availability and does not justify starting provider acquisition from hover.