suaveplan/openspec/archive/2026-04-19-enterprise-domain-normalizer/proposal.md

OpenSpec Change: enterprise-domain-normalizer

• Change ID: enterprise-domain-normalizer
• Package: @suaveplan/domain-normalizer
• Category: universal
• Target path: universal/data/domain-normalizer
• Status: PROPOSED
• Date: 2026-04-19
• Reference spec: /mnt/s/web/suaveplan/enterprise/domain-normalizer.md

Summary

Normalisation, matching, and alias-canonicalisation for internet domain names. Given heterogeneous URL/domain input (including common aliases such as m.youtube.com → youtube.com), produces a canonical registrable domain and computes similarity scores for deduplication.

Current-state audit (genesis)

Package does not exist yet — fresh build.

Dependencies

• Workspace: none (leaf)
• External (via catalog): zod, tslib, @opentelemetry/api, tldts (public-suffix resolution) — appropriate catalogs
• Dev (via catalog): vitest, @vitest/coverage-istanbul, fast-check, mitata

Preserved public surface

Normaliser

• normalizeDomain(input, config?), normalizeUrl(url, config?)
• getRegistrableDomain(input), getSubdomain(input), getDomainGroup(input)

Aliases

• BUILT_IN_ALIASES, getAliasGroup, getCanonicalDomain, isKnownAlias, resetAliasCache

Matcher

• matchDomains(a, b, config?), computeSimilarity(a, b), findMatchingDomains, groupDomains, levenshteinDistance

Types

DomainAliasGroup, DomainMatch, DomainMatchReason, NormalizedUrl, NormalizerConfig

New genesis additions

• Codes: DOMAIN_NORMALIZER.INVALID_INPUT, DOMAIN_NORMALIZER.PSL_LOOKUP_FAILED.
• Zod schemas for NormalizerConfig, DomainAliasGroup, NormalizedUrl.
• OTel counter domain_normalizer.normalize.total{outcome}, histogram domain_normalizer.normalize.duration_ms.
• Property tests: normalise is idempotent; getRegistrableDomain is a fixed point under repeated application.

Impact

• Adds one new package: universal/data/domain-normalizer
• Adds one new spec capability: domain-normalizer