in reviewhumanPR #193Communication
Add `versioned` comms plugin with schema-versioned wire envelopes and forward-compatible unknown-field preservation
This PR adds a new reference comms implementation that ships a schema-versioned wire envelope for Nanda Town. It enables safe rolling upgrades by preserving unknown fields from newer-minor peers and rejecting unknown-major versions instead…
Author
@pseudo-jay
github profile →- Status
- In review
- Opened on
- Jul 11
- Branch
- pseudo-jay-comms-schema-evolution
Description
The pitch.
This PR adds a new reference comms implementation that ships a schema-versioned wire envelope for Nanda Town. It enables safe rolling upgrades by preserving unknown fields from newer-minor peers and rejecting unknown-major versions instead of silently mis-decoding them.
**What changed**
- Implemented `VersionedComms` in versioned.py
- Registered the plugin as `("comms", "versioned")` in plugins.py
- Added entry-point `versioned = "nest_plugins_reference.comms.versioned:VersionedComms"` in pyproject.toml
- Added compatibility tests in test_comms_schema_evolution.py
- Added a mixed-version scenario in comms_schema_evolution.yaml
- Added migration guidance in schema_version_migration.md
- Linked the migration note from quickstart.md
**Key behavior**
- Every envelope now carries explicit `schema_version` and `kind`
- A newer-minor envelope preserves unknown top-level fields in `metadata["_unknown"]`
- Re-serialization re-emits preserved unknown fields
- A higher major version is rejected with `UnsupportedSchemaError`
**Testing**
- Full suite run: `PYTHONPATH=$(printf "%s:" packages/* | sed 's/:$//') /opt/miniconda3/envs/nanda/bin/python -m pytest -q`
- Result: `1295 passed, 1 skipped, 1 deselected`
**Notes**
- Branch: `pseudo-jay-comms-schema-evolution`
- Fork PR URL: `https://github.com/pseudo-jay/nandatown/pull/new/pseudo-jay-comms-schema-evolution`
Try it
Open PR on GitHubView diffCheckout locally
git fetch origin pull/193/head:pr-193
git checkout pr-193