v0.3.0-alpha.1

Pre-release adding column masks, per-call NUMERIC loss-of-precision control, and Statement.Params extraction. Mirrored semantics still track cloud.google.com/go/spanner v1.91.0; go.mod stays at the v1.84.1 MVS floor.

Added

• Column masks for the plain-Go-value helpers, written as either an include list or an exclude list (update-mask style):
  • WithColumns(columns ...string) — include mask; output keeps struct declaration order regardless of argument order.
  • WithoutColumns(columns ...string) — exclude mask.
  • Apply to MutationColumnsAndValues, MutationMap, and ParamsMap via the new ColumnMaskOption type. Strict validation: unknown columns, read-only columns in a write-shaped include list, or combining include with exclude return the new sentinel ErrInvalidColumnMask. Excluding a read-only column is a no-op.
• WithLossOfPrecisionHandling(spanner.NumericError | spanner.NumericRound) (EncodeOption, accepted by ValueOf, StructColumnsAndValues, ValuesFromSlice, ArrayValueFromSlice): per-call NUMERIC loss-of-precision control reusing the client's enum vocabulary. The client's package-global spanner.LossOfPrecisionHandling is never read; the per-call default is spanner.NumericError (validate, returning ErrNumericOutOfRange), while the client's global defaults to NumericRound — pass it explicitly for silent rounding. Like the client, rounding affects only the fractional part.
• ParamsMap(v any, opts ...ColumnMaskOption) (map[string]any, error): struct → column-name-to-Go-value map for binding as spanner.Statement Params, with no GCV conversion (the client encodes at execution). Unlike the write-shaped MutationMap, read-only fields are included (they are ordinary bindable values) and an include mask may name them.

Changed

• Docs: corrected an inaccurate claim that the client's default loss-of-precision handling is NumericError; the client's global actually defaults to NumericRound (silent rounding). spanenc's per-call default deliberately stays on validation.

Design notes

Two deliberate API decisions from review: option types stay split (EncodeOption vs ColumnMaskOption) so option applicability is fixed at compile time, and ParamsMap / MutationMap stay separate functions — the read-only handling is determined by the destination (Params vs mutations), so it is encoded in the function name rather than an option.