Reject invalid with_array_type registrations

with_array_type is now partial. It errors if the registration would
cause recursive decode (element OID is itself an array OID), collide
with an existing scalar or built-in array OID, use an OID already
registered as a custom element OID, or self-reference. Previously
these misconfigurations were silently accepted and would cause
incorrect behavior or stack overflow at decode time.

Closes #168

Author: SeanTAllen

.release-notes/next-release.md

@@ -794,7 +794,7 @@ session.execute(PreparedQuery("SELECT $1::int4[]",
 ```pony
 let registry = CodecRegistry
   .with_codec(600, PointBinaryCodec)
-  .with_array_type(1017, 600)
+  .with_array_type(1017, 600)?
 ```
 
 Multi-dimensional arrays are not supported and will fall back to `String` (text format) or `RawBytes` (binary format).

.release-notes/reject-invalid-array-type-registration.md

@@ -0,0 +1,26 @@
+## Reject invalid with_array_type registrations
+
+`CodecRegistry.with_array_type()` is now partial. It errors if the registration would cause problems at decode time:
+
+- `element_oid` is itself an array OID (built-in or custom), which would cause unbounded recursion during decode
+- `array_oid` collides with a registered scalar or built-in array OID
+- `array_oid` is already registered as a custom element OID
+- `array_oid == element_oid`
+
+Previously, these misconfigurations were silently accepted and would cause incorrect behavior or stack overflow at decode time. Now the error surfaces at registry construction, where the OID values are visible in the source.
+
+Before:
+
+```pony
+let registry = CodecRegistry
+  .with_codec(600, PointBinaryCodec)
+  .with_array_type(1017, 600)
+```
+
+After:
+
+```pony
+let registry = CodecRegistry
+  .with_codec(600, PointBinaryCodec)
+  .with_array_type(1017, 600)?
+```

CLAUDE.md

@@ -131,7 +131,7 @@ Only one operation is in-flight at a time. The queue serializes execution. `quer
 - `StreamingResultReceiver` interface (tag) — `pg_stream_batch(Session, Rows)`, `pg_stream_complete(Session)`, `pg_stream_failed(Session, (PreparedQuery | NamedPreparedQuery), (ErrorResponseMessage | ClientQueryError))`. Pull-based: session delivers batches via `pg_stream_batch`; client calls `fetch_more()` for the next batch or `close_stream()` to end early
 - `PipelineReceiver` interface (tag) — `pg_pipeline_result(Session, USize, Result)`, `pg_pipeline_failed(Session, USize, (PreparedQuery | NamedPreparedQuery), (ErrorResponseMessage | ClientQueryError))`, `pg_pipeline_complete(Session)`. Each query result/failure is delivered with its pipeline index. `pg_pipeline_complete` always fires last
 - `Codec` interface (val) — `format(): U16`, `encode(FieldDataTypes): Array[U8] val ?`, `decode(Array[U8] val): FieldData ?`. Wire format codec for a PostgreSQL type. Encode stays closed (`FieldDataTypes`), decode is open (`FieldData`). Built-in codecs are primitives (zero-allocation singletons)
-- `CodecRegistry` class (val) — maps OIDs to text and binary `Codec` instances. Immutable — `with_codec(oid, codec)` returns a new registry with the codec added or replacing an existing one. `with_array_type(array_oid, element_oid)` registers a custom array type mapping. `array_oid_for(element_oid)` returns the array OID (built-in + custom, 0 if unknown). Supports chaining: `CodecRegistry.with_codec(600, A).with_array_type(1017, 600)`. Default constructor populates all built-in codecs. `decode(oid, format, data)` is partial — returns `FieldData` for known OIDs, fallbacks for unknown OIDs (unknown text→`String`, unknown binary→`RawBytes`), and errors when a registered codec's `decode()` fails. Intercepts array OIDs before normal codec dispatch. `has_binary_codec(oid)` for format selection (includes array OIDs)
+- `CodecRegistry` class (val) — maps OIDs to text and binary `Codec` instances. Immutable — `with_codec(oid, codec)` returns a new registry with the codec added or replacing an existing one. `with_array_type(array_oid, element_oid)?` registers a custom array type mapping (partial — errors if element_oid is an array OID, array_oid collides with a registered OID, array_oid is already a custom element OID, or array_oid == element_oid). `array_oid_for(element_oid)` returns the array OID (built-in + custom, 0 if unknown). Supports chaining: `CodecRegistry.with_codec(600, A).with_array_type(1017, 600)?`. Default constructor populates all built-in codecs. `decode(oid, format, data)` is partial — returns `FieldData` for known OIDs, fallbacks for unknown OIDs (unknown text→`String`, unknown binary→`RawBytes`), and errors when a registered codec's `decode()` fails. Intercepts array OIDs before normal codec dispatch. `has_binary_codec(oid)` for format selection (includes array OIDs)
 - `ClientQueryError` — union type `(SessionNeverOpened | SessionClosed | SessionNotAuthenticated | DataError)`
 - `DatabaseConnectInfo` — val class grouping database authentication parameters (user, password, database). Passed to `Session.create()` alongside `ServerConnectInfo`.
 - `ServerConnectInfo` — val class grouping connection parameters (auth, host, service, ssl_mode). Passed to `Session.create()` as the first parameter. Also used by `_CancelSender`.
@@ -170,7 +170,7 @@ Codec-based decoding via `CodecRegistry.decode(oid, format_code, data)`. Extende
 - Text codecs (`_text_codecs.pony`): `_BoolTextCodec`, `_ByteaTextCodec`, `_Int2TextCodec`, `_Int4TextCodec`, `_Int8TextCodec`, `_Float4TextCodec`, `_Float8TextCodec`, `_DateTextCodec`, `_TimeTextCodec`, `_TimestampTextCodec`, `_TimestamptzTextCodec`, `_IntervalTextCodec` (supports all four `intervalstyle` formats: `postgres`, `postgres_verbose`, `iso_8601`, `sql_standard` — detected via heuristic in `decode()`), `_TextPassthroughTextCodec`, `_OidTextCodec`, `_NumericTextCodec`, `_UuidTextCodec`, `_JsonbTextCodec`
 - `_ArrayOidMap` (`_array_oid_map.pony`): static bidirectional mapping between element OIDs and array OIDs (23 entries). Methods: `element_oid_for(array_oid)`, `array_oid_for(element_oid)`, `is_array_oid(oid)`
 - `_ArrayEncoder` (`_array_encoder.pony`): encodes `PgArray` to binary array wire format. Dispatches element encoding on Pony runtime types. String elements routed by `element_oid`: uuid → `_UuidBinaryCodec`, jsonb → `_JsonbBinaryCodec`, oid → `_OidBinaryCodec`, numeric → `_NumericBinaryCodec`; all others → raw UTF-8 bytes. Coupling: element encoding must stay in sync with `_FrontendMessage.bind()` and `_binary_codecs.pony`
-- `CodecRegistry` (`codec_registry.pony`): maps OIDs to codecs. Adds `_custom_array_element_oids: Map[U32, U32] val` field for custom array type registrations. Default constructor populates all built-ins. `with_codec(oid, codec)` returns a new registry with the codec added/replaced. `with_array_type(array_oid, element_oid)` returns a new registry with the custom array mapping added. `array_oid_for(element_oid): U32` returns the array OID for the given element OID. `decode()` intercepts array OIDs before normal codec dispatch via two-phase array decoding: `_parse_binary_array`/`_parse_text_array` extract structure and raw element bytes (errors fall back), then `_decode_array_elements` decodes each element via the element codec (errors propagate). `has_binary_codec()` checks array OIDs too. `_with_codec` constructor (type-private) used internally by `with_codec`
+- `CodecRegistry` (`codec_registry.pony`): maps OIDs to codecs. Adds `_custom_array_element_oids: Map[U32, U32] val` field for custom array type registrations. Default constructor populates all built-ins. `with_codec(oid, codec)` returns a new registry with the codec added/replaced. `with_array_type(array_oid, element_oid)?` returns a new registry with the custom array mapping added (errors if element_oid is an array OID, array_oid collides with a registered OID, array_oid is already a custom element OID, or array_oid == element_oid). `array_oid_for(element_oid): U32` returns the array OID for the given element OID. `decode()` intercepts array OIDs before normal codec dispatch via two-phase array decoding: `_parse_binary_array`/`_parse_text_array` extract structure and raw element bytes (errors fall back), then `_decode_array_elements` decodes each element via the element codec (errors propagate). `has_binary_codec()` checks array OIDs too. `_with_codec` constructor (type-private) used internally by `with_codec`
 - `_ParamEncoder` (`_param_encoder.pony`): derives PostgreSQL OIDs from `FieldDataTypes` parameter values for Parse messages. Takes `registry: CodecRegistry` parameter; `PgArray` arm uses `registry.array_oid_for(a.element_oid)`
 
 **Encode error handling:** `_FrontendMessage.bind()` is partial — it errors if parameter encoding fails. Takes `registry: CodecRegistry` parameter (with default `CodecRegistry`); pre-encodes `PgArray` parameters via `_ArrayEncoder` before the `recover val` block. `_QueryReady.try_run_query()` uses a build-before-transition pattern: wire messages are constructed before transitioning to an in-flight state, so encode errors deliver `DataError` to the receiver without leaving the state machine inconsistent. Pipeline queries build message parts into an `iso` array in `ref` scope (where error handling has full access to the session and receiver), then consume the array into a `recover val` block for concatenation.

postgres/_test.pony

@@ -446,6 +446,7 @@ actor \nodoc\ Main is TestList
     test(_TestNumericBinaryCodecEncodeRoundtrip)
     test(_TestCodecRegistryHasBinaryCodecArray)
     test(_TestCodecRegistryWithArrayType)
+    test(_TestCodecRegistryWithArrayTypeRejectsInvalid)
     test(_TestCodecRegistryArrayOidFor)
     test(_TestIntegrationArraySelectBinary)
     test(_TestIntegrationArraySelectText)

postgres/_test_array.pony

@@ -946,11 +946,56 @@ class \nodoc\ iso _TestCodecRegistryWithArrayType is UnitTest
   fun name(): String =>
     "CodecRegistry/WithArrayType"
 
-  fun apply(h: TestHelper) =>
-    let registry = CodecRegistry.with_array_type(1017, 600)
+  fun apply(h: TestHelper) ? =>
+    let registry = CodecRegistry.with_array_type(1017, 600)?
     h.assert_true(registry.has_binary_codec(1017))
     h.assert_eq[U32](1017, registry.array_oid_for(600))
 
+class \nodoc\ iso _TestCodecRegistryWithArrayTypeRejectsInvalid
+  is UnitTest
+  fun name(): String =>
+    "CodecRegistry/WithArrayType/RejectsInvalid"
+
+  fun apply(h: TestHelper) =>
+    // Built-in array OID as element_oid (would cause recursion)
+    h.assert_error({()? => CodecRegistry.with_array_type(9999, 1007)? })
+
+    // Custom array OID as element_oid (would cause recursion)
+    h.assert_error({()? =>
+      CodecRegistry.with_array_type(9998, 600)?
+        .with_array_type(9999, 9998)?
+    })
+
+    // Self-referential mapping
+    h.assert_error({()? => CodecRegistry.with_array_type(600, 600)? })
+
+    // array_oid collides with built-in scalar codec (int4 = OID 23)
+    h.assert_error({()? => CodecRegistry.with_array_type(23, 600)? })
+
+    // array_oid collides with built-in array OID (int4[] = OID 1007)
+    h.assert_error({()? => CodecRegistry.with_array_type(1007, 600)? })
+
+    // array_oid collides with custom binary-only codec
+    h.assert_error({()? =>
+      CodecRegistry
+        .with_codec(9000, _TestPointCodec)
+        .with_array_type(9000, 600)?
+    })
+
+    // array_oid collides with custom text-only codec
+    h.assert_error({()? =>
+      CodecRegistry
+        .with_codec(9001, _TestUppercaseTextCodec)
+        .with_array_type(9001, 600)?
+    })
+
+    // array_oid is already a custom element OID (would cause decode
+    // to misinterpret element data as array structure)
+    h.assert_error({()? =>
+      CodecRegistry.with_array_type(9998, 600)?
+        .with_array_type(600, 500)?
+    })
+
 class \nodoc\ iso _TestCodecRegistryArrayOidFor is UnitTest
   fun name(): String =>
     "CodecRegistry/ArrayOidFor"

postgres/codec_registry.pony

@@ -12,7 +12,7 @@ class val CodecRegistry
   ```pony
   let registry = CodecRegistry
     .with_codec(600, PointBinaryCodec)
-    .with_array_type(1017, 600)
+    .with_array_type(1017, 600)?
   let session = Session(server_info, db_info, notify where registry = registry)
   ```
   """
@@ -124,13 +124,41 @@ class val CodecRegistry
       end
     end
 
-  fun val with_array_type(array_oid: U32, element_oid: U32): CodecRegistry =>
+  fun val with_array_type(array_oid: U32, element_oid: U32)
+    : CodecRegistry ?
+  =>
     """
     Returns a new registry with a custom array type mapping. This enables
     decode of arrays whose element type is a custom codec-registered OID.
     Supports chaining with `with_codec`:
-    `CodecRegistry.with_codec(600, PointCodec).with_array_type(1017, 600)`.
+    `CodecRegistry.with_codec(600, PointCodec).with_array_type(1017, 600)?`.
+
+    Errors if:
+    - `element_oid` is itself an array OID (built-in or custom), which would
+      cause unbounded recursion during decode
+    - `array_oid` collides with a registered scalar or built-in array OID
+    - `array_oid` is already registered as a custom element OID
+    - `array_oid == element_oid`
     """
+    // Reject self-referential mapping
+    if array_oid == element_oid then error end
+
+    // Reject element OIDs that are themselves array OIDs (recursion)
+    if _ArrayOidMap.is_array_oid(element_oid) then error end
+    if _custom_array_element_oids.contains(element_oid) then error end
+
+    // Reject array OIDs that collide with registered scalar codecs
+    if _text_codecs.contains(array_oid) then error end
+    if _binary_codecs.contains(array_oid) then error end
+
+    // Reject array OIDs that collide with built-in array OIDs
+    if _ArrayOidMap.is_array_oid(array_oid) then error end
+
+    // Reject array OIDs that are already registered as custom element OIDs
+    for elem_oid in _custom_array_element_oids.values() do
+      if elem_oid == array_oid then error end
+    end
+
     CodecRegistry._with_array_type(this, array_oid, element_oid)
 
   new val _with_array_type(base: CodecRegistry, array_oid: U32,

postgres/postgres.pony

@@ -344,7 +344,7 @@ For custom array types (arrays of custom codec-registered OIDs), use
 ```pony
 let registry = CodecRegistry
   .with_codec(600, PointBinaryCodec)
-  .with_array_type(1017, 600)
+  .with_array_type(1017, 600)?
 ```
 
 ## Custom Codecs