docs: spec out msgpack encoding and gRPC transport story
Two design slices captured under docs/specs/ for later pickup:
- msgpack_encoding.md: proto schemas as IDL, msgpack as wire format.
Default mp_map keyed by field number; ARRAY/MP_TUPLE opt-ins for
box.space feeders; WKT bridging to MP_DATETIME / MP_INTERVAL.
- grpc_transports.md: Connect-JSON over HTTP/1.1 as default external
transport, net.box tunnel for in-cluster, explicit no on HTTP/2
termination (recommend Envoy). Conformance anchored on
connectrpc/conformance — same framed-runner shape as the existing
protobuf conformance harness.
PLAN.md cross-links both specs from M4, Open Questions, and Non-goals.
docs: refresh README + PLAN; add api-modes and codegen notes
README.md
* Status table reflects current state: text-format encode + decode,
-0.0 preservation, strict FieldMask, all-green proto3 conformance.
* Conformance baseline jumped to 1493 / 416 / 0 failures (was
1389 / 0 / 79 in the old table); explains the 1313+18 skipped
tests are all TestAllTypesProto2, deferred separately.
* Layout walks the full runtime/pb/ tree (lazy, text, json, wkt,
grpc, parser, dynamic, fileset, descriptor_pb).
* Generated API section calls out the three-mode design and links
to docs/api-modes.md and docs/codegen.md.
PLAN.md
* Section 2 ("Current state") rewritten — no longer claims M0;
lists what's actually in the codebase.
* M1, M2, M3 marked done with [x] checkboxes (had stale [ ]
markers across items that have been shipping for months).
* M5 conformance numbers updated to current baseline; calls out
the three commits that closed the proto3 suite (text decode,
-0 codec, JSON strict pass).
* M7 text-format parser entry updated: 416 ✓ / 0 failures (was
406 / 10 expected before the codec -0 fix).
* Added an M7 entry for the JSON strict-validation pass (six
classes of relaxation now enforced).
docs/api-modes.md (new)
* When to use full vs runtime (descriptor / reflect) vs lazy.
* Concrete code shapes for each, plus what the generated
Person_encode actually looks like in full mode.
* Descriptor-shape contract that ties all three together.
* Lazy: SoA index rationale, sparse-read vs dense-read trade-offs,
cross-over points from bench numbers.
docs/codegen.md (new)
* Pipeline diagram, CLI options, what gets emitted per .proto.
* Walk through the inline (full) mode emission with annotated
generated code.
* Runtime mode: pb.finalize_message's per-field writer/reader
closures and why they exist.
* Hot-path rules the generated code observes (no pairs(), 64-bit
as cdata, SoA over AoS for large index structures, keep hot
helpers small).
* Plugin source map; where to extend for a new wire type.
* Proto2 deferral section: what it would take and why we punt.
docs: handoff brief for the pb.text.decode slice
Self-contained brief targeting the 408 proto3 TextFormatInput tests
still skipped after the encoder + SGROUP work. Covers existing
surface (text.lua encode-only, parser.lua schema parser, conformance
dispatch), grammar buckets the suite exercises (10 categories with
upstream test counts), files to touch, LuaJIT/cdata/box.NULL
conventions, and a verifying-locally checklist. Suggested
recursive-descent shape mirrors runtime/pb/parser.lua's cursor
mechanics.
No code changes; positions the next slice without committing to a
specific implementation schedule.