Skip to content

Migration guide: 0.x to 1.0

SYNAPSE CHANNEL 0.x releases are pre-1.0 development releases. The 1.0 line makes the documented public surfaces stable: the package export facade, the wire message vocabulary, the federation consumer primitives, and the classified CLI tiers.

This guide is for operators who pin SYNAPSE in local hubs, fleet waiters, automation scripts, or out-of-tree integrations.

What stays stable

The stable contract is guarded in CI:

  • Package exports: synapse_channel.__all__, pinned by tests/test_public_api.py.
  • Wire vocabulary: MessageType name/value pairs, reserved envelope keys, and WIRE_PROTOCOL_VERSION, pinned by tests/test_wire_surface_freeze.py.
  • Federation primitives: out-of-tree imports listed in tests/test_federation_consumer_contract.py.
  • CLI tiers: subcommand classification in synapse_channel.surface_taxonomy, checked by tests/test_surface_taxonomy.py.
  • Capability counts: tools/capability_manifest.py --check.

The wire-protocol integer is independent from the package version. A 1.0 package may still speak wire protocol 2; only wire-incompatible changes bump WIRE_PROTOCOL_VERSION.

Before upgrading

  1. Record the installed version and hub health:
synapse --version
synapse doctor
  1. Stop long-running fleet waiters cleanly, then upgrade the package in the environment that owns the hub and in each waiter environment:
python -m pip install --upgrade synapse-channel

For pipx installs:

pipx upgrade synapse-channel

  1. Restart the hub first, then restart waiters. Mixed 0.x and 1.0 peers may connect if their wire versions overlap, but a single fleet should converge on one package line before release or sustained soak work.

  2. Re-run:

synapse --version
synapse doctor
synapse who

Integration checks

For Python integrations, import only names from synapse_channel.__all__ or the documented deep federation primitives. Treat any other deep import as private unless a guide names it.

For wire clients:

  • Read the hub's protocol_version from the welcome frame or /health.
  • Accept the negotiated-down version reported by the client or multi-hub fetcher.
  • Do not assume package version and wire version are the same value.
  • Keep unknown fields in envelopes and JSON documents non-fatal unless the specific command documents a closed schema.

For CLI automation:

  • Prefer stable-tier commands for daily operations.
  • Pin exact package versions when using experimental commands.
  • Review the changelog for any 0.x command-shape changes before upgrading.

Store and dashboard checks

The event store remains SQLite/WAL. Before a release cut or fleet upgrade, keep a copy of the hub database and verify the read-side feeds you rely on:

synapse event-query ./hub.db "universal-receipts all" --json
synapse causality ./hub.db --json
synapse reliability ./hub.db --json

For dashboards started with --feeds-db, verify the durable feed endpoints after the hub upgrade:

  • /events.json
  • /state-at.json
  • /receipts.json
  • /operator-actions.json
  • /reliability.json

When an upgrade fails

  1. Keep the database copy.
  2. Capture synapse doctor and the hub startup error.
  3. Downgrade only the package, not the database file, unless the changelog says a migration changed the store format.
  4. File the failure with the package version, WIRE_PROTOCOL_VERSION, command line, and the smallest event-store excerpt that reproduces the read-side problem.

Release-cut checklist

Before declaring a 1.0 upgrade complete:

  • tests/test_public_api.py passes with the exact export list.
  • tests/test_wire_surface_freeze.py passes with the exact wire map.
  • tests/test_federation_consumer_contract.py passes.
  • tools/capability_manifest.py --check passes.
  • mkdocs build --strict includes this guide.
  • The fleet's hub and waiters report the intended package version.