feat(pg): asDomain() + PgRecordParser fixes + cross-check vs live PG + fuzz

[oyvindberg]

Summary

• PgType.asDomain(name) + combined asDomain(name, f, g) for the JDBC view of a PG CREATE DOMAIN. Renames the typename, registers the underlying type as a query-analyzer alias (PG JDBC resolves domains in ResultSetMetaData), and switches the array codec to text-parsing so domain arrays decode correctly. The combined overload wraps once at the scalar level so .array() carries the wrapper through with no list-level bijection.
• Two parser bugs fixed in PgType.array() + PgRecordParser:
  • array() was hardcoding , as the resulting type's arrayDelimiter (broke box[]); now propagates the original delimiter end-to-end through readCompositeList.
  • parseUnquotedArrayElement didn't track {} brace depth or \"…\" quoted-string state (broke multi-dim dom_jsonb[][], text[][], etc.).
• Kotlin and Scala wrappers expose .asDomain(...) (both forms). PostgreSQL docs + snippets in all three languages updated.

Test plan

Library

• bleep compile foundations-jdbc foundations-jdbc-hikari foundations-jdbc-spring foundations-jdbc-kotlin foundations-jdbc-scala documentation-examples-java documentation-examples-kotlin documentation-examples-scala — green.

Pure-unit parser

• bleep test foundations-jdbc-test -o dev.typr.foundations.PgRecordParserTest — 40 passing, with a new shared corpus covering 1-D, bare-nested (incl. multi-level + JSON-leaf + backslash-escaped quotes), and ;-delim cases.

Cross-check against live PG

• bleep test foundations-jdbc-test -o dev.typr.foundations.PgRecordParserAgreementTest — for every entry in the shared PgArrayParseCases corpus, ask PG to parse the same string under the case's named cast (text[] for 1-D/bare-nested, box[] for ;-delim) and assert agreement on element list, dimensions, and top-level count. Each case explicitly carries its castSqlType so PG's textual array semantics aren't ambiguous.

Domains

• bleep test foundations-jdbc-test -o dev.typr.foundations.PgDomainTest — 12 passing. Covers the user-pattern Name.pgType.array().to(Bijection), ~27 representative scalar+array roundtrips, ENUM, COMPOSITE, CHECK violation, NOT NULL violation, Optional<DomainType>, domain-over-domain, and domain-as-composite-field.

Adversarial roundtrip fuzz

• bleep test foundations-jdbc-test -o dev.typr.foundations.PgFuzzRoundtripTest — 7 passing. ~60 adversarial strings paired explicitly to a PgType<T>, threaded through:

  • scalar
  • 1-D array singleton
  • 1-D array multi-element (mixed with \"NULL\" and \"{a,b};\\\"\\\\\" siblings to force per-element disambiguation)
  • asDomain wrapper (scalar + array)
  • single-field composite (different encode path: PgRecordParser.parse)
  • two-field composite (sibling field independently adversarial)
  • array of composite (two layers of escape rules composing)
  • composite with array field (inverse layering)

  Corpus covers: empty/whitespace, every PG-significant punctuation (,;:|::{}()[]), every quote/backslash combo (incl. escape lookalikes), every case of NULL/null/nUlL lookalikes, control characters (CR LF TAB VT FF BEL DEL), multi-byte UTF-8 (®, emoji, ZWJ family, skin-tone), RTL Arabic + Hebrew, CJK, combining marks, ZWJ + ZWSP + BOM mid-string, soft hyphen, NBSP, supplementary plane (4-byte UTF-8), 100x-repeated braces, 100x-repeated \\\".

Full PG matrix

• bleep test foundations-jdbc-test -o dev.typr.foundations.PgTypeTest — every Element runs as both itself and as an asDomain variant through native + streaming + JSON in-mem + JSON DB + composite + function + procedure + OUT + INOUT + analysis. ENUM + COMPOSITE entries added with their setup DDL carried in the entry.

Notes

• Domain variants drop hasIdentity unconditionally — the base entry already proves the underlying's = operator works, and PG does not always define = on a domain in its own right (domain-over-enum has no operator class). Documented in the matrix.
• ENUM entries marked .noCallable() because PG won't promote varchar → enum at procedure-overload resolution. COMPOSITE marked .noStreaming() because COPY-text encoding splits inside composite literals at the comma. Both are pre-existing library limitations the matrix now surfaces explicitly.
• One bare-nested case ({{\"{\\\\\"k\\\\\": 1}\"},{\"{\\\\\"k\\\\\": 2}\"}} — the canonical jsonb[][] shape) is parser-only against PG's text[] cast: PG's rectangularity check tries to descend into the inner {\"k\":...} thinking it's another array dimension. Documented in the corpus and skipped on the PG cross-check.

🤖 Generated with Claude Code