Initial Commit

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

@@ -0,0 +1,45 @@
+# 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`