spec(schema/pg): design typed array values and operators

[scottescue]

Outcome

Ratify one coherent PostgreSQL array contract across schema declarations, generated values, encoding/scanning, snapshots, and query operations.

Context

One-dimensional array declarations exist, but typed generated values and the broader array-operation surface are not yet designed normatively. Implementation must not choose public value shapes or operator semantics ad hoc.

Decisions required

• Typed generated Go values for supported one-dimensional element families.
• Nullable scan/encode behavior and element encoder identity.
• Snapshot and code-generation representation boundaries.
• Exact containment, ANY/ALL, subscripting, empty-input, and dialect behavior.
• Whether multidimensional arrays are designed now or remain explicitly unsupported.

Out of scope

• PostgreSQL range types.
• Implementing builders or generated APIs before ratification.
• Claiming broad array parity without a complete lifecycle contract.

Ratification criteria

• Normative schema, codegen, type, query, and dialect specs agree on one array representation.
• Nullability, scanning, encoding, snapshots, and supported operators have testable examples.
• Empty input, unsupported element/dimension, and non-PostgreSQL behavior return explicit stable errors.
• Follow-up implementation issues can be split and estimated without further public-API decisions.