> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rixxui.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rixx UI Protocol 0.1

> Experimental framed protocol, transaction invariants, graph validation, and recovery behavior.

# 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

```jsonl theme={null}
["begin","0.1","main","rixx.core@0.1",0,"tx-welcome"]
["node",1,"title","Heading",{"text":"Welcome","level":1},[]]
["node",2,"root","Stack",{"gap":"lg"},["title"]]
["commit",3,"root",1]
```

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

```text theme={null}
["begin", protocolVersion, surfaceId, catalogId, baseRevision, transactionId]
```

`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

```text theme={null}
["node", sequence, nodeId, componentName, props, childIds]
```

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

```text theme={null}
["data", sequence, jsonPointer, jsonValue]
```

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

```text theme={null}
["deleteNode", sequence, nodeId]
["deleteData", sequence, jsonPointer]
```

Deletion is explicit. `null` and omission never imply deletion.

### Commit

```text theme={null}
["commit", sequence, rootNodeId, newRevision]
```

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

### Abort

```text theme={null}
["abort", sequence, errorCode, safeMessage]
```

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.