Skip to content

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

Closed

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.

Activity

  1. apstndb commented on Jun 10, 2026

    @apstndb
    OwnerAuthor

    Priority raised (spanenc downstream). Documentation-only; unblocks clear adoption-boundary messaging for spanenc consumers. Docs PR incoming.

  2. added
    priority:highShould be addressed soon; correctness or release blocker
    on Jun 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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