Skip to main content

​
Rixx UI Protocol 0.1

​
Status

Version 0.1 is an experimental canonical intermediate representation. It is transport-independent and is validated by @rixx-ui/protocol. The protocol is an internal/advanced renderer layer during pre-alpha. Normal React consumers pass accumulated source to RUIRenderer and do not construct or persist protocol records.

​
Framing

Every frame contains one complete JSON record. A transport must not expose partially recovered JSON as an authoritative operation.
  • SSE: one record per data event.
  • WebSocket: one record per message.
  • Raw HTTP stream: RFC 7464 JSON text sequences.
  • Fixtures and logs: one record per JSONL line.
The private Studio SSE API multiplexes protocol records with source, log, reset, error, and completion events. That development envelope is not the canonical protocol transport contract. Records are tagged tuples. Fixed prefixes stay compact; component props remain named objects so schema changes cannot reorder meaning.

​
Transaction

The first record is always begin. Every following record has a contiguous sequence number equal to its zero-based record position. The last record is exactly one commit or abort.

​
Records

​
Begin

transactionId correlates records and diagnostics. The current runtime does not store a completed-transaction registry, so production idempotency remains a host or future transport responsibility.

​
Node

Node records replace the complete staged definition for their ID. Version 0.1 rejects duplicate node definitions within one transaction rather than relying on last-write-wins behavior.

​
Data

Data replaces the value at an RFC 6901 JSON Pointer. Tool data should normally enter through this channel, not through model-generated language text.

​
Deletions

Deletion is explicit. null and omission never imply deletion.

​
Commit

newRevision must equal baseRevision + 1. The runtime applies all staged operations, validates the resulting graph and policy, then swaps the committed snapshot atomically.

​
Abort

Abort is terminal and leaves the committed snapshot unchanged. Messages must not contain secrets or unredacted user data.

​
Graph invariants

  • Node IDs are unique and stable.
  • The committed root exists.
  • Every structural child reference resolves.
  • The reachable graph is acyclic.
  • Child lists contain no duplicates.
  • IDs, props, arrays, strings, depth, operation counts, and total bytes are bounded.
  • Components and props validate against the negotiated catalog.
  • Action requests remain inert until commit and pass to host policy independently from component validity.

​
Recovery

  • Invalid frame: quarantine it and resume only at a transport frame boundary.
  • Sequence gap: reject/discard staging; a transport may reconnect or obtain a host snapshot.
  • Stale base revision: reject and require host resynchronization.
  • Invalid transaction: retain the last known-good committed graph.
  • Unknown or unsupported component: reject catalog validation. Optional widget negotiation is not implemented in version 0.1.
  • Interrupted stream without commit or abort: discard staged state.

​
Versioning

Protocol, catalog, language, and transport versions are independent.
  • Protocol major changes alter record shape or semantics.
  • Protocol minor changes are additive and capability-negotiated.
  • Catalog IDs are immutable and include a semantic version.
  • Removed tuple positions and operation tags are never reused.
  • Unknown operations fail the transaction unless a future protocol explicitly marks them optional.