Enforce Geospatial / KML / KMZ complexity limits on upload

[guardian-automation]

Job Story:

When a user uploads a geospatial file, I want Guardian to accept either KML or KMZ format and validate it against defined complexity limits, so that I get a clear, specific error if my file exceeds supported limits rather than a silent failure or timeout, or downstream performance issues.

Note:

Guardian will not perform any automatic file compression or transformation. Both KML and KMZ are supported as valid upload formats as-is. The problem to solve is file complexity — uncompressed size, embedded image size, feature count, and network link count — not the format or on-disk size of the uploaded file itself.

Acceptance Criteria:

• Given an upload, the system accepts both .kml and .kmz file types natively — no conversion between formats is performed.
• Given a KML or KMZ upload, the system evaluates it against defined complexity thresholds: uncompressed KML size, embedded image size (per file within a KMZ), total document-wide feature count, and number of network links.
• Given a file that exceeds any complexity threshold, the system rejects the upload with a distinct "file too large" error code that identifies which specific threshold(s) were exceeded (size, image size, feature count, network links), so the user knows what to fix.
• Given a file within all thresholds, the system accepts it as uploaded (KML or KMZ) without modification.
• Guardian does not compress, optimize, or otherwise transform the file on the user's behalf; if a file is rejected, the user is responsible for reducing its complexity using their own tooling before re-uploading.
• Given the complexity thresholds (uncompressed size, image size, feature count, network link count), they are configurable, not hardcoded, so they can be reviewed and tuned independently.
• Given a rejection event, it is logged with file size, feature count, network link count, and which threshold(s) triggered the rejection, for debugging and future threshold tuning.

Open Question:

Exact thresholds for Guardian are still TBD across all dimensions (size, image size, feature count, network links). A decision should be made after reviewing existing platform examples (Google Maps, Esri) below — not specified in this story yet.

Additional Context / Artifacts:

Reference: Google Maps JavaScript API (KmlLayer) restrictions

https://developers.google.com/maps/documentation/javascript/kmllayer#restrictions

Dimension	Google Maps Limit
Max fetched file size (raw KML, raw GeoRSS, or compressed KMZ)	3MB
Max uncompressed KML file size	10MB
Max uncompressed image file size in KMZ files	500KB per file
Max number of network links	10
Max total document-wide features	1,000
Number of KML layers per map	No fixed number — based on combined KmlLayer count + total URL length; ~10–20 layers typical before hitting the limit. Workarounds: shorten URLs, or consolidate into one KML with NetworkLinks to individual KML URLs.

Reference: Esri ArcGIS Online / Map Viewer

• 10MB max uncompressed KML (hard limit) — https://doc.arcgis.com/en/arcgis-online/reference/kml.htm
• Warning message reference (24088) — https://doc.esri.com/en/arcgis-pro/latest/help/sharing/analyzer-warning-messages/24088-unzipped-kml-size-of-mb-exceeds-the-map-viewer-limit.html

Reference: Verra PRR

Verra lists 100MB limit for PRR

https://verra.org/digital-project-review-report-prr-faqs/