added ServerConfigurationMapping

split up Abstractions so we have one type per file.

pgLabII.PgUtils/ConnectionStrings/NpgsqlCodec.cs

@@ -8,6 +8,21 @@ using Npgsql;
 
 namespace pgLabII.PgUtils.ConnectionStrings;
 
+/// <summary>
+/// Parser/formatter for Npgsql-style .NET connection strings. We intentionally do not
+/// rely on NpgsqlConnectionStringBuilder here because:
+/// - We need a lossless, format-agnostic round-trip to our ConnectionDescriptor, including
+///   unknown/extension keys and per-host port lists. NpgsqlConnectionStringBuilder normalizes
+///   names, may drop unknown keys or coerce values, which breaks lossless conversions.
+/// - We support multi-host with per-host ports and want to preserve the original textual
+///   representation across conversions. The builder flattens/rewrites these details.
+/// - We aim to keep pgLabII.PgUtils independent from Npgsql's evolving parsing rules and
+///   version-specific behaviors to ensure stable UX and deterministic tests.
+/// - We need symmetric formatting matching our other codecs (libpq/URL/JDBC) and consistent
+///   quoting rules across formats.
+/// If required, we still reference Npgsql for enums and interop types, but parsing/formatting
+/// is done by this small, well-tested custom codec for full control and stability.
+/// </summary>
 public sealed class NpgsqlCodec : IConnectionStringCodec
 {
     public ConnStringFormat Format => ConnStringFormat.Npgsql;