# Capability Spec: sitemap

**Package**: `@suaveplan/sitemap`
**Version**: 0.0.0 (genesis)
**Status**: ADDED

---

## ADDED Requirements

### SM-01 — Sitemap XML compliance

`SitemapGenerator.build(urls, options?)` MUST produce XML conforming to `https://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd`. A single sitemap MUST NOT exceed 50 000 URLs or 50 MiB uncompressed; exceeding either MUST throw `SITEMAP.TOO_LARGE` recommending sharding via `SitemapIndexGenerator`.

### SM-02 — URL validation

`SitemapUrl.loc` MUST be absolute and ≤ 2 048 bytes. `priority` MUST be in `[0.0, 1.0]`. `changefreq` MUST be a member of `VALID_CHANGE_FREQS`. Invalid values MUST surface as `SITEMAP.INVALID_PRIORITY` / `SITEMAP.INVALID_CHANGE_FREQ` / `SITEMAP.INVALID_URL`.

### SM-03 — Image / video extensions

`addImagesToUrl(url, images)` and `addVideosToUrl(url, videos)` MUST emit the corresponding `image:image` / `video:video` child elements under the `xmlns:image` / `xmlns:video` namespaces. Up to 1 000 images per URL (per spec) and 1 000 videos per URL MUST be permitted.

### SM-04 — Sitemap index

`SitemapIndexGenerator.build(subSitemaps)` MUST emit a `sitemapindex` document. Each `<sitemap>` MUST carry `loc` + optional `lastmod`.

### SM-05 — Incremental rebuild

`computeUrlHash(url)` MUST produce a stable fingerprint over the URL + metadata such that reordering of insignificant fields does not affect the hash. `IncrementalBuilder` MUST report `ChangeDetectionResult { added, removed, modified }` given prior and current URL sets.

### SM-06 — Compression

`compressSitemap(xml)` MUST return `{ bytes, size, ratio }` using gzip level 6 by default. `decompressSitemap(bytes)` MUST round-trip back to the original XML. `generateCompressionHeaders` MUST return `{ 'content-encoding': 'gzip', 'content-type': 'application/xml' }`.

### SM-07 — Observability

Every build / parse / compress MUST record the corresponding duration histogram and outcome counter.