✨ feat(replication): version the operation envelope

[gaborbernat]

The availability contracts express staleness and recovery as a serial frontier over the peryx-replication change serial, yet the change stream carries no per-operation provenance a follower can reason about before it applies an operation. A Change holds a serial and an opaque payload. It does not say which schema version encoded it, which primary authored it, which authority generation was in force, or what kind of mutation it is, and nothing bounds an untrusted peer's bytes before they parse. Storage durability and a later transport both need to depend on the stream, so replication first needs a stable, versioned envelope around each operation.

OperationEnvelope wraps the existing version-1 Change instead of opening a second replication stream. It adds a schema_version, the source identity, an AuthorityEpoch fencing token that a failover advances, an OperationKind naming the mutation, and an optional W3C TraceContext. An operation's identity is the (source, epoch, serial) triple: stable across replay, idempotent to apply, and safe to log. encode and decode round-trip through JSON. decode treats its input as untrusted: it rejects bytes past a size or nesting-depth limit before parsing, requires a schema version within SUPPORTED_SCHEMA_VERSIONS, and validates the traceparent when a trace context is present. SchemaVersion::negotiate is the version-negotiation surface, returning the newest version two ends share.

Two compatibility rules keep a rolling upgrade between adjacent schema versions safe. Decoding ignores fields it does not recognize, so a newer producer that adds a field stays readable by an older consumer inside the supported window, and it refuses any version outside that window instead of guessing at a schema it cannot model. Debug and Display render the operation kind, version, and identity, and they omit the payload bytes and metadata values, so a log line carries what an operator needs to trace an operation without its contents. A local benchmark reports the encode and decode cost and allocation count for a representative wheel upload and registry manifest push, holding metadata replication clear of becoming a blob transport.

Persistence, transport, and applying operations stay downstream and out of scope; this change defines the wire and persistence type, its bounded encode and decode, and its version-negotiation surface.

Closes #503

[read-the-docs-community]

Documentation build overview

📚 peryx | 🛠️ Build #33643127 | 📁 Comparing 705408f against latest (f84e85e)

  🔍 Preview build  

134 files changed · ± 134 modified

± Modified

• brand-book.html
• index.html
• brand/index.html
• contributing/index.html
• core/index.html
• ecosystems/index.html
• contributing/architecture/index.html
• contributing/benchmarking/index.html
• contributing/release/index.html
• core/access-explained/index.html
• and 124 more...

[codspeed-hq]

Merging this PR will not alter performance

✅ 32 untouched benchmarks
⏩ 94 skipped benchmarks¹

---

_{Comparing gaborbernat:feat/versioned-replication-op-envelope-503 (705408f) with main (9adc775)}

Footnotes

1. 94 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩