Skip to content

docs: record spanenc in adoption boundaries and cross-link from gcvctor #233

Description

@apstndb

Problem

spanenc now exists as the client-semantics layer over gcvctor: reflection-based Go value → GCV conversion mirroring the client's internal encodeValue / structToMutationParams / spanner struct-tag semantics (with structfields hosting the Apache-2.0 fork of internal/fields). spanvalue's docs predate it:

  1. AGENTS.md "Adoption boundaries" lists string→GCV parsing (spanbridge) and PG table cells (spanpg), but not the reflection/client-tag-semantics boundary. Without it, future feature requests like "make gcvctor accept arbitrary Go values / struct tags" have no recorded answer. Suggested line: reflection-based, client-encodeValue-compatible Go value → GCV (struct tags, Null* wrappers, spanner.Encoder, typed-NULL inference) lives in spanenc; gcvctor stays explicit, strict constructors with caller-supplied types.
  2. gcvctor doc.go / README discoverability: a one-line pointer ("for converting arbitrary Go values with the official client's encoding semantics, see github.com/apstndb/spanenc") mirrors the existing pointer to the root spanvalue package and helps pkg.go.dev visitors find the right layer.

Both changes are documentation-only.

Context

spanenc deliberately reuses gcvctor for all GCV construction (strictness invariants: no nil Types, typed NULLs, strict ARRAY/STRUCT assembly) and documents its divergences from the client on its side. Keeping the boundary recorded on the spanvalue side closes the loop.

Metadata

Metadata

Assignees

No one assigned

    Labels

    priority:highShould be addressed soon; correctness or release blocker

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions