feat(protocol): negotiate display and native input

fixtures/conformance/gateway-input-feedback-v1.tsv

@@ -7,6 +7,8 @@ valid-relative-mouse	1	gateway_input	hex=564749310304fffe0003	valid
 valid-utf8-scalar	1	gateway_input	hex=564749310403e29883	valid
 valid-controller	1	gateway_input	hex=5647493105110200030004ffff00010002000300040005	valid
 valid-controller-release	1	gateway_input	hex=5647493105110200000000000000000000000000000000	valid
+valid-absolute-mouse	1	gateway_input	hex=56474931060804d202370a0005a0	valid
+valid-scroll	1	gateway_input	hex=564749310704ff880078	valid
 valid-idr	1	gateway_feedback	hex=5647463100010000	valid
 valid-fec	1	gateway_feedback	hex=56474631000200150000002a000500030002000a000200080002140001	valid
 valid-terminal-receipt	1	gateway_feedback	hex=5647463100030000	valid
@@ -18,6 +20,11 @@ invalid-input-kind	1	gateway_input	hex=564749317f00	invalid:kind
 invalid-input-reserved	1	gateway_input	hex=564749310203010101	invalid:reserved
 invalid-input-utf8	1	gateway_input	hex=564749310402c328	invalid:utf8
 invalid-input-length	1	gateway_input	hex=564749310104010200	invalid:length
+invalid-absolute-zero-viewport	1	gateway_input	hex=56474931060800000000000005a0	invalid:field
+invalid-absolute-x-out-of-range	1	gateway_input	hex=5647493106080a0000000a0005a0	invalid:field
+invalid-absolute-y-out-of-range	1	gateway_input	hex=564749310608000005a00a0005a0	invalid:field
+invalid-absolute-length	1	gateway_input	hex=56474931060700000000010001	invalid:length
+invalid-scroll-length	1	gateway_input	hex=5647493107020000	invalid:length
 invalid-feedback-direction	1	gateway_feedback	hex=5647463101020000	invalid:direction
 invalid-terminal-receipt-direction	1	gateway_feedback	hex=5647463101030000	invalid:direction
 invalid-terminal-receipt-body	1	gateway_feedback	hex=5647463100030001ff	invalid:length

fixtures/conformance/tunnel-v1.tsv

@@ -2,5 +2,8 @@ id	version	kind	input	expected
 tunnel-current	1	tunnel	offered=1;feature=control.v1	valid
 tunnel-n-minus-1	0	tunnel	offered=0;feature=control.v1	valid
 tunnel-n-minus-2	-1	tunnel	offered=-1;feature=control.v1	valid
+tunnel-display-request	1	tunnel	offered=1;feature=display.request.v1	valid
+tunnel-absolute-input	1	tunnel	offered=1;feature=input.absolute.v1	valid
+tunnel-scroll-input	1	tunnel	offered=1;feature=input.scroll.v1	valid
 tunnel-unsupported	1	tunnel	offered=2;feature=control.v1	invalid:unsupported_version
 tunnel-no-control	1	tunnel	offered=1;feature=media.video	invalid:unsupported_feature

fixtures/manifest.json

@@ -10,5 +10,5 @@
     "fixtures/conformance/gateway-input-feedback-v1.tsv",
     "fixtures/conformance/tunnel-v1.tsv"
   ],
-  "corpus_sha256": "544ba8765b4ddcfbe807d1d6e6788fe03d06b8e50d1424b82e4e512312e51248"
+  "corpus_sha256": "4f8bf520d4f61588235b00776b21202ff701b20d6d11b461037b911c2117852b"
 }

frames/gateway-input-feedback-v1.md

@@ -4,12 +4,14 @@ This grammar is carried only in an authenticated Phase 3C gateway session. It
 is deliberately provider-neutral: it never carries provider routes,
 certificates, credentials, opaque provider packets, clipboard bytes, files, or
 client-folder data. It does not change the v1 datagram header or any existing
-release candidate.
+kind encoding; the new kinds require explicit feature negotiation and a new
+immutable Protocol release candidate.
 
 ## `input.sequenced.v1` payload (`VGI1`)
 
-All multibyte fields are unsigned big-endian. The payload has exactly six bytes
+All multibyte fields are big-endian and unsigned unless a field is explicitly
-of header followed by the declared body:
+marked signed. The payload has exactly six bytes of header followed by the
+declared body:
 
 | Offset | Size | Field | Rule |
 |---:|---:|---|---|
@@ -32,12 +34,16 @@ during cleanup.
 | `0x03` | relative mouse | `delta_x` (i16), `delta_y` (i16). |
 | `0x04` | UTF-8 scalar | exactly one valid UTF-8 Unicode scalar, one through four bytes. |
 | `0x05` | controller state | `controller` (0 through 15), `active_mask` (u16), `button_flags` (u16), `left_trigger` (u8), `right_trigger` (u8), `left_x` (i16), `left_y` (i16), `right_x` (i16), `right_y` (i16), `extra_button_flags` (u16). A zero `active_mask` and zero state is release. |
+| `0x06` | absolute mouse | `x` (u16), `y` (u16), `viewport_width` (u16), `viewport_height` (u16). Viewport dimensions must be nonzero and each coordinate must be strictly smaller than its corresponding dimension. |
+| `0x07` | high-resolution scroll | `vertical_delta` (i16), `horizontal_delta` (i16). Positive and negative values preserve the client scroll direction without provider-specific scaling. |
 
-Keyboard, mouse button, UTF-8, and controller messages are delivered over the
+Keyboard, mouse button, UTF-8, controller, absolute mouse, and scroll messages
-gateway's reliable ordered input flow. Relative mouse is a state change, not a
+are delivered over the gateway's reliable ordered input flow. Relative and
-pressed-state entry. The gateway maps the validated values to the provider's
+absolute mouse movement and scroll are state changes, not pressed-state
-separate keyboard, mouse, UTF-8, and controller control messages; it does not
+entries. Kinds `0x06` and `0x07` are accepted only when the session advertises
-forward this envelope to the provider.
+`input.absolute.v1` and `input.scroll.v1`, respectively. The gateway maps the
+validated values to the provider's separate input messages; it does not forward
+this envelope to the provider.
 
 ## Reliable control payload (`VGF1`)
 

gen/go/protocol/protocol.go

@@ -13,7 +13,7 @@ import (
 	"time"
 )
 
-const SchemaSHA256 = "a86cbdaf2cfb884e3d98467968007e731ca55c6f6eb6dbd5cd6b95e062a9b058"
+const SchemaSHA256 = "b2bb0a8ac8ef56dbc0e1443eeb5b3028be9e71ec2f5fd8e73928d71b7cd9340c"
 const ProtocolVersion = "1.0.0"
 const CurrentWireVersion = "1"
 const NMinus1WireVersion = "0"
@@ -65,6 +65,8 @@ type BrokerSession struct {
 	RequestedAt          string           `json:"requested_at"`
 	EndedAt              string           `json:"ended_at,omitempty"`
 	Version              int64            `json:"version"`
+	RequestedDisplayMode *DisplayMode     `json:"requested_display_mode,omitempty"`
+	EffectiveDisplayMode *DisplayMode     `json:"effective_display_mode,omitempty"`
 }
 
 type CapabilityProfile struct {
@@ -134,6 +136,12 @@ type DeviceRegistrationRequest struct {
 	PublicKey     string `json:"public_key"`
 }
 
+type DisplayMode struct {
+	ResolutionWidth  int64 `json:"resolution_width"`
+	ResolutionHeight int64 `json:"resolution_height"`
+	Fps              int64 `json:"fps"`
+}
+
 type EntitledPool struct {
 	PoolID          string `json:"pool_id"`
 	Name            string `json:"name"`
@@ -265,6 +273,7 @@ type ManifestGateway struct {
 type ManifestProfile struct {
 	ID          string         `json:"id"`
 	Bounds      ManifestBounds `json:"bounds"`
+	DisplayMode *DisplayMode   `json:"display_mode,omitempty"`
 }
 
 type ManifestTunnel struct {
@@ -388,6 +397,7 @@ type SessionRequest struct {
 	PoolID               string           `json:"pool_id"`
 	IdempotencyKey       string           `json:"idempotency_key"`
 	PolicySnapshot       AllocationPolicy `json:"policy_snapshot"`
+	RequestedDisplayMode *DisplayMode     `json:"requested_display_mode,omitempty"`
 }
 
 type StableError struct {
@@ -767,6 +777,16 @@ func (v BrokerSession) Validate() error {
 	if v.Version != 0 && v.Version < 1 {
 		violations = append(violations, FieldViolation{Field: "version", Code: "minimum"})
 	}
+	if v.RequestedDisplayMode != nil {
+		if err := v.RequestedDisplayMode.Validate(); err != nil {
+			violations = append(violations, FieldViolation{Field: "requested_display_mode", Code: "invalid_object"})
+		}
+	}
+	if v.EffectiveDisplayMode != nil {
+		if err := v.EffectiveDisplayMode.Validate(); err != nil {
+			violations = append(violations, FieldViolation{Field: "effective_display_mode", Code: "invalid_object"})
+		}
+	}
 	if len(violations) > 0 {
 		return ValidationError{Violations: violations}
 	}
@@ -812,6 +832,12 @@ func DecodeBrokerSession(data []byte) (BrokerSession, error) {
 	if raw, ok := fields["version"]; !ok || bytes.Equal(bytes.TrimSpace(raw), []byte("null")) {
 		return value, ValidationError{Violations: []FieldViolation{{Field: "version", Code: "required"}}}
 	}
+	if raw, ok := fields["requested_display_mode"]; ok && bytes.Equal(bytes.TrimSpace(raw), []byte("null")) {
+		return value, ValidationError{Violations: []FieldViolation{{Field: "requested_display_mode", Code: "invalid_object"}}}
+	}
+	if raw, ok := fields["effective_display_mode"]; ok && bytes.Equal(bytes.TrimSpace(raw), []byte("null")) {
+		return value, ValidationError{Violations: []FieldViolation{{Field: "effective_display_mode", Code: "invalid_object"}}}
+	}
 	decoder := json.NewDecoder(bytes.NewReader(data))
 	decoder.DisallowUnknownFields()
 	if err := decoder.Decode(&value); err != nil {
@@ -1625,6 +1651,84 @@ func EncodeDeviceRegistrationRequest(value DeviceRegistrationRequest) ([]byte, e
 	return json.Marshal(value)
 }
 
+func (v DisplayMode) Validate() error {
+	var violations []FieldViolation
+	if v.ResolutionWidth == 0 {
+		violations = append(violations, FieldViolation{Field: "resolution_width", Code: "required"})
+	}
+	if v.ResolutionWidth != 0 && v.ResolutionWidth < 320 {
+		violations = append(violations, FieldViolation{Field: "resolution_width", Code: "minimum"})
+	}
+	if v.ResolutionWidth > 16384 {
+		violations = append(violations, FieldViolation{Field: "resolution_width", Code: "maximum"})
+	}
+	if v.ResolutionHeight == 0 {
+		violations = append(violations, FieldViolation{Field: "resolution_height", Code: "required"})
+	}
+	if v.ResolutionHeight != 0 && v.ResolutionHeight < 200 {
+		violations = append(violations, FieldViolation{Field: "resolution_height", Code: "minimum"})
+	}
+	if v.ResolutionHeight > 8640 {
+		violations = append(violations, FieldViolation{Field: "resolution_height", Code: "maximum"})
+	}
+	if v.Fps == 0 {
+		violations = append(violations, FieldViolation{Field: "fps", Code: "required"})
+	}
+	if v.Fps != 0 && v.Fps < 1 {
+		violations = append(violations, FieldViolation{Field: "fps", Code: "minimum"})
+	}
+	if v.Fps > 240 {
+		violations = append(violations, FieldViolation{Field: "fps", Code: "maximum"})
+	}
+	if len(violations) > 0 {
+		return ValidationError{Violations: violations}
+	}
+	return nil
+}
+
+func DecodeDisplayMode(data []byte) (DisplayMode, error) {
+	var value DisplayMode
+	if len(data) > 1024*1024 {
+		return value, errors.New("protocol payload exceeds limit")
+	}
+	var fields map[string]json.RawMessage
+	if err := json.Unmarshal(data, &fields); err != nil {
+		return value, err
+	}
+	if raw, ok := fields["fps"]; !ok || bytes.Equal(bytes.TrimSpace(raw), []byte("null")) {
+		return value, ValidationError{Violations: []FieldViolation{{Field: "fps", Code: "required"}}}
+	}
+	if raw, ok := fields["resolution_height"]; !ok || bytes.Equal(bytes.TrimSpace(raw), []byte("null")) {
+		return value, ValidationError{Violations: []FieldViolation{{Field: "resolution_height", Code: "required"}}}
+	}
+	if raw, ok := fields["resolution_width"]; !ok || bytes.Equal(bytes.TrimSpace(raw), []byte("null")) {
+		return value, ValidationError{Violations: []FieldViolation{{Field: "resolution_width", Code: "required"}}}
+	}
+	decoder := json.NewDecoder(bytes.NewReader(data))
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(&value); err != nil {
+		return value, err
+	}
+	var trailing any
+	if err := decoder.Decode(&trailing); err != io.EOF {
+		if err == nil {
+			return value, errors.New("trailing JSON value")
+		}
+		return value, err
+	}
+	if err := value.Validate(); err != nil {
+		return value, err
+	}
+	return value, nil
+}
+
+func EncodeDisplayMode(value DisplayMode) ([]byte, error) {
+	if err := value.Validate(); err != nil {
+		return nil, err
+	}
+	return json.Marshal(value)
+}
+
 func (v EntitledPool) Validate() error {
 	var violations []FieldViolation
 	if v.PoolID == "" {
@@ -3202,6 +3306,11 @@ func (v ManifestProfile) Validate() error {
 	if err := v.Bounds.Validate(); err != nil {
 		violations = append(violations, FieldViolation{Field: "bounds", Code: "invalid_object"})
 	}
+	if v.DisplayMode != nil {
+		if err := v.DisplayMode.Validate(); err != nil {
+			violations = append(violations, FieldViolation{Field: "display_mode", Code: "invalid_object"})
+		}
+	}
 	if len(violations) > 0 {
 		return ValidationError{Violations: violations}
 	}
@@ -3223,6 +3332,9 @@ func DecodeManifestProfile(data []byte) (ManifestProfile, error) {
 	if raw, ok := fields["id"]; !ok || bytes.Equal(bytes.TrimSpace(raw), []byte("null")) {
 		return value, ValidationError{Violations: []FieldViolation{{Field: "id", Code: "required"}}}
 	}
+	if raw, ok := fields["display_mode"]; ok && bytes.Equal(bytes.TrimSpace(raw), []byte("null")) {
+		return value, ValidationError{Violations: []FieldViolation{{Field: "display_mode", Code: "invalid_object"}}}
+	}
 	decoder := json.NewDecoder(bytes.NewReader(data))
 	decoder.DisallowUnknownFields()
 	if err := decoder.Decode(&value); err != nil {
@@ -4655,6 +4767,11 @@ func (v SessionRequest) Validate() error {
 	if err := v.PolicySnapshot.Validate(); err != nil {
 		violations = append(violations, FieldViolation{Field: "policy_snapshot", Code: "invalid_object"})
 	}
+	if v.RequestedDisplayMode != nil {
+		if err := v.RequestedDisplayMode.Validate(); err != nil {
+			violations = append(violations, FieldViolation{Field: "requested_display_mode", Code: "invalid_object"})
+		}
+	}
 	if len(violations) > 0 {
 		return ValidationError{Violations: violations}
 	}
@@ -4685,6 +4802,9 @@ func DecodeSessionRequest(data []byte) (SessionRequest, error) {
 	if raw, ok := fields["pool_id"]; !ok || bytes.Equal(bytes.TrimSpace(raw), []byte("null")) {
 		return value, ValidationError{Violations: []FieldViolation{{Field: "pool_id", Code: "required"}}}
 	}
+	if raw, ok := fields["requested_display_mode"]; ok && bytes.Equal(bytes.TrimSpace(raw), []byte("null")) {
+		return value, ValidationError{Violations: []FieldViolation{{Field: "requested_display_mode", Code: "invalid_object"}}}
+	}
 	decoder := json.NewDecoder(bytes.NewReader(data))
 	decoder.DisallowUnknownFields()
 	if err := decoder.Decode(&value); err != nil {

gen/manifest.json

@@ -12,7 +12,7 @@
       "2"
     ]
   },
-  "generator_sha256": "00fdba050eb924a54dd3d63aac0a38560341b675f0de4e3e9631ee895057a9b6",
+  "generator_sha256": "992235a56d3467313148f86e47931f247591e4c8de737b55ac9c9eee35725fc5",
   "protocol_version": "1.0.0",
-  "schema_sha256": "a86cbdaf2cfb884e3d98467968007e731ca55c6f6eb6dbd5cd6b95e062a9b058"
+  "schema_sha256": "b2bb0a8ac8ef56dbc0e1443eeb5b3028be9e71ec2f5fd8e73928d71b7cd9340c"
 }

gen/rust/protocol.rs

@@ -1,6 +1,6 @@
 // Code generated by tools/generate.py; DO NOT EDIT.
 #![allow(non_snake_case)]
-pub const SCHEMA_SHA256: &str = "a86cbdaf2cfb884e3d98467968007e731ca55c6f6eb6dbd5cd6b95e062a9b058";
+pub const SCHEMA_SHA256: &str = "b2bb0a8ac8ef56dbc0e1443eeb5b3028be9e71ec2f5fd8e73928d71b7cd9340c";
 pub const CURRENT_WIRE_VERSION: &str = "1";
 pub const N_MINUS_1_WIRE_VERSION: &str = "0";
 pub const N_MINUS_2_WIRE_VERSION: &str = "-1";
@@ -136,11 +136,13 @@ pub struct BrokerSession {
     requestedAt: String,
     endedAt: Option<String>,
     version: i64,
+    requestedDisplayMode: Option<DisplayMode>,
+    effectiveDisplayMode: Option<DisplayMode>,
 }
 
 impl BrokerSession {
-    pub fn new(id: String, principalId: String, poolId: String, assignmentId: Option<String>, state: String, policySnapshot: AllocationPolicy, reconnectDeadline: Option<String>, outcome: Option<String>, failureCode: Option<String>, cleanupState: String, idempotencyKey: String, correlationId: String, requestedAt: String, endedAt: Option<String>, version: i64) -> Result<Self, ValidationError> {
+    pub fn new(id: String, principalId: String, poolId: String, assignmentId: Option<String>, state: String, policySnapshot: AllocationPolicy, reconnectDeadline: Option<String>, outcome: Option<String>, failureCode: Option<String>, cleanupState: String, idempotencyKey: String, correlationId: String, requestedAt: String, endedAt: Option<String>, version: i64, requestedDisplayMode: Option<DisplayMode>, effectiveDisplayMode: Option<DisplayMode>) -> Result<Self, ValidationError> {
-        let value = Self { id, principalId, poolId, assignmentId, state, policySnapshot, reconnectDeadline, outcome, failureCode, cleanupState, idempotencyKey, correlationId, requestedAt, endedAt, version };
+        let value = Self { id, principalId, poolId, assignmentId, state, policySnapshot, reconnectDeadline, outcome, failureCode, cleanupState, idempotencyKey, correlationId, requestedAt, endedAt, version, requestedDisplayMode, effectiveDisplayMode };
         value.validate()?;
         Ok(value)
     }
@@ -184,6 +186,12 @@ impl BrokerSession {
             if value.len() > 64 { return Err(ValidationError::new("ended_at", "max_length")); }
         }
         if self.version < 1 { return Err(ValidationError::new("version", "minimum")); }
+        if let Some(value) = &self.requestedDisplayMode {
+            value.validate().map_err(|_| ValidationError::new("requested_display_mode", "invalid_object"))?;
+        }
+        if let Some(value) = &self.effectiveDisplayMode {
+            value.validate().map_err(|_| ValidationError::new("effective_display_mode", "invalid_object"))?;
+        }
         Ok(())
     }
     pub fn id(&self) -> &String { &self.id }
@@ -201,6 +209,8 @@ impl BrokerSession {
     pub fn requestedAt(&self) -> &String { &self.requestedAt }
     pub fn endedAt(&self) -> &Option<String> { &self.endedAt }
     pub fn version(&self) -> &i64 { &self.version }
+    pub fn requestedDisplayMode(&self) -> &Option<DisplayMode> { &self.requestedDisplayMode }
+    pub fn effectiveDisplayMode(&self) -> &Option<DisplayMode> { &self.effectiveDisplayMode }
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -494,6 +504,33 @@ impl DeviceRegistrationRequest {
     pub fn publicKey(&self) -> &String { &self.publicKey }
 }
 
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DisplayMode {
+    resolutionWidth: i64,
+    resolutionHeight: i64,
+    fps: i64,
+}
+
+impl DisplayMode {
+    pub fn new(resolutionWidth: i64, resolutionHeight: i64, fps: i64) -> Result<Self, ValidationError> {
+        let value = Self { resolutionWidth, resolutionHeight, fps };
+        value.validate()?;
+        Ok(value)
+    }
+    pub fn validate(&self) -> Result<(), ValidationError> {
+        if self.resolutionWidth < 320 { return Err(ValidationError::new("resolution_width", "minimum")); }
+        if self.resolutionWidth > 16384 { return Err(ValidationError::new("resolution_width", "maximum")); }
+        if self.resolutionHeight < 200 { return Err(ValidationError::new("resolution_height", "minimum")); }
+        if self.resolutionHeight > 8640 { return Err(ValidationError::new("resolution_height", "maximum")); }
+        if self.fps < 1 { return Err(ValidationError::new("fps", "minimum")); }
+        if self.fps > 240 { return Err(ValidationError::new("fps", "maximum")); }
+        Ok(())
+    }
+    pub fn resolutionWidth(&self) -> &i64 { &self.resolutionWidth }
+    pub fn resolutionHeight(&self) -> &i64 { &self.resolutionHeight }
+    pub fn fps(&self) -> &i64 { &self.fps }
+}
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct EntitledPool {
     poolId: String,
@@ -1080,11 +1117,12 @@ impl ManifestGateway {
 pub struct ManifestProfile {
     id: String,
     bounds: ManifestBounds,
+    displayMode: Option<DisplayMode>,
 }
 
 impl ManifestProfile {
-    pub fn new(id: String, bounds: ManifestBounds) -> Result<Self, ValidationError> {
+    pub fn new(id: String, bounds: ManifestBounds, displayMode: Option<DisplayMode>) -> Result<Self, ValidationError> {
-        let value = Self { id, bounds };
+        let value = Self { id, bounds, displayMode };
         value.validate()?;
         Ok(value)
     }
@@ -1093,10 +1131,14 @@ impl ManifestProfile {
         if !self.id.is_empty() && self.id.len() < 1 { return Err(ValidationError::new("id", "min_length")); }
         if self.id.len() > 128 { return Err(ValidationError::new("id", "max_length")); }
         self.bounds.validate().map_err(|_| ValidationError::new("bounds", "invalid_object"))?;
+        if let Some(value) = &self.displayMode {
+            value.validate().map_err(|_| ValidationError::new("display_mode", "invalid_object"))?;
+        }
         Ok(())
     }
     pub fn id(&self) -> &String { &self.id }
     pub fn bounds(&self) -> &ManifestBounds { &self.bounds }
+    pub fn displayMode(&self) -> &Option<DisplayMode> { &self.displayMode }
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -1613,11 +1655,12 @@ pub struct SessionRequest {
     poolId: String,
     idempotencyKey: String,
     policySnapshot: AllocationPolicy,
+    requestedDisplayMode: Option<DisplayMode>,
 }
 
 impl SessionRequest {
-    pub fn new(clientDeviceId: String, deviceKeyId: String, poolId: String, idempotencyKey: String, policySnapshot: AllocationPolicy) -> Result<Self, ValidationError> {
+    pub fn new(clientDeviceId: String, deviceKeyId: String, poolId: String, idempotencyKey: String, policySnapshot: AllocationPolicy, requestedDisplayMode: Option<DisplayMode>) -> Result<Self, ValidationError> {
-        let value = Self { clientDeviceId, deviceKeyId, poolId, idempotencyKey, policySnapshot };
+        let value = Self { clientDeviceId, deviceKeyId, poolId, idempotencyKey, policySnapshot, requestedDisplayMode };
         value.validate()?;
         Ok(value)
     }
@@ -1635,6 +1678,9 @@ impl SessionRequest {
         if !self.idempotencyKey.is_empty() && self.idempotencyKey.len() < 1 { return Err(ValidationError::new("idempotency_key", "min_length")); }
         if self.idempotencyKey.len() > 256 { return Err(ValidationError::new("idempotency_key", "max_length")); }
         self.policySnapshot.validate().map_err(|_| ValidationError::new("policy_snapshot", "invalid_object"))?;
+        if let Some(value) = &self.requestedDisplayMode {
+            value.validate().map_err(|_| ValidationError::new("requested_display_mode", "invalid_object"))?;
+        }
         Ok(())
     }
     pub fn clientDeviceId(&self) -> &String { &self.clientDeviceId }
@@ -1642,6 +1688,7 @@ impl SessionRequest {
     pub fn poolId(&self) -> &String { &self.poolId }
     pub fn idempotencyKey(&self) -> &String { &self.idempotencyKey }
     pub fn policySnapshot(&self) -> &AllocationPolicy { &self.policySnapshot }
+    pub fn requestedDisplayMode(&self) -> &Option<DisplayMode> { &self.requestedDisplayMode }
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]

gen/swift/Protocol.swift

@@ -1,7 +1,7 @@
 // Code generated by tools/generate.py; DO NOT EDIT.
 import Foundation
 public typealias JSONObject = [String: String]
-public let schemaSHA256 = "a86cbdaf2cfb884e3d98467968007e731ca55c6f6eb6dbd5cd6b95e062a9b058"
+public let schemaSHA256 = "b2bb0a8ac8ef56dbc0e1443eeb5b3028be9e71ec2f5fd8e73928d71b7cd9340c"
 public let currentWireVersion = "1"
 public let nMinus1WireVersion = "0"
 public let nMinus2WireVersion = "-1"
@@ -148,6 +148,8 @@ public struct BrokerSession: Codable, Equatable {
     public let requestedAt: String
     public let endedAt: String?
     public let version: Int64
+    public let requestedDisplayMode: DisplayMode?
+    public let effectiveDisplayMode: DisplayMode?
     enum CodingKeys: String, CodingKey {
         case id = "id"
         case principalId = "principal_id"
@@ -164,9 +166,11 @@ public struct BrokerSession: Codable, Equatable {
         case requestedAt = "requested_at"
         case endedAt = "ended_at"
         case version = "version"
+        case requestedDisplayMode = "requested_display_mode"
+        case effectiveDisplayMode = "effective_display_mode"
     }
 
-    public init(id: String, principalId: String, poolId: String, assignmentId: String?, state: String, policySnapshot: AllocationPolicy, reconnectDeadline: String?, outcome: String?, failureCode: String?, cleanupState: String, idempotencyKey: String, correlationId: String, requestedAt: String, endedAt: String?, version: Int64) throws {
+    public init(id: String, principalId: String, poolId: String, assignmentId: String?, state: String, policySnapshot: AllocationPolicy, reconnectDeadline: String?, outcome: String?, failureCode: String?, cleanupState: String, idempotencyKey: String, correlationId: String, requestedAt: String, endedAt: String?, version: Int64, requestedDisplayMode: DisplayMode?, effectiveDisplayMode: DisplayMode?) throws {
         self.id = id
         self.principalId = principalId
         self.poolId = poolId
@@ -182,6 +186,8 @@ public struct BrokerSession: Codable, Equatable {
         self.requestedAt = requestedAt
         self.endedAt = endedAt
         self.version = version
+        self.requestedDisplayMode = requestedDisplayMode
+        self.effectiveDisplayMode = effectiveDisplayMode
         try validate()
     }
 
@@ -189,7 +195,7 @@ public struct BrokerSession: Codable, Equatable {
         let all = try decoder.container(keyedBy: AnyCodingKey.self)
         for key in all.allKeys where CodingKeys(stringValue: key.stringValue) == nil { throw ContractValidationError(field: key.stringValue, code: "unknown_field") }
         let c = try decoder.container(keyedBy: CodingKeys.self)
-        try self.init(id: try c.decode(String.self, forKey: .id), principalId: try c.decode(String.self, forKey: .principalId), poolId: try c.decode(String.self, forKey: .poolId), assignmentId: try c.decodeIfPresent(String.self, forKey: .assignmentId), state: try c.decode(String.self, forKey: .state), policySnapshot: try c.decode(AllocationPolicy.self, forKey: .policySnapshot), reconnectDeadline: try c.decodeIfPresent(String.self, forKey: .reconnectDeadline), outcome: try c.decodeIfPresent(String.self, forKey: .outcome), failureCode: try c.decodeIfPresent(String.self, forKey: .failureCode), cleanupState: try c.decode(String.self, forKey: .cleanupState), idempotencyKey: try c.decode(String.self, forKey: .idempotencyKey), correlationId: try c.decode(String.self, forKey: .correlationId), requestedAt: try c.decode(String.self, forKey: .requestedAt), endedAt: try c.decodeIfPresent(String.self, forKey: .endedAt), version: try c.decode(Int64.self, forKey: .version))
+        try self.init(id: try c.decode(String.self, forKey: .id), principalId: try c.decode(String.self, forKey: .principalId), poolId: try c.decode(String.self, forKey: .poolId), assignmentId: try c.decodeIfPresent(String.self, forKey: .assignmentId), state: try c.decode(String.self, forKey: .state), policySnapshot: try c.decode(AllocationPolicy.self, forKey: .policySnapshot), reconnectDeadline: try c.decodeIfPresent(String.self, forKey: .reconnectDeadline), outcome: try c.decodeIfPresent(String.self, forKey: .outcome), failureCode: try c.decodeIfPresent(String.self, forKey: .failureCode), cleanupState: try c.decode(String.self, forKey: .cleanupState), idempotencyKey: try c.decode(String.self, forKey: .idempotencyKey), correlationId: try c.decode(String.self, forKey: .correlationId), requestedAt: try c.decode(String.self, forKey: .requestedAt), endedAt: try c.decodeIfPresent(String.self, forKey: .endedAt), version: try c.decode(Int64.self, forKey: .version), requestedDisplayMode: try c.contains(.requestedDisplayMode) ? c.decode(DisplayMode.self, forKey: .requestedDisplayMode) : nil, effectiveDisplayMode: try c.contains(.effectiveDisplayMode) ? c.decode(DisplayMode.self, forKey: .effectiveDisplayMode) : nil)
     }
 
     public func validate() throws {
@@ -235,6 +241,12 @@ public struct BrokerSession: Codable, Equatable {
             if ISO8601DateFormatter().date(from: value) == nil { throw ContractValidationError(field: "ended_at", code: "invalid_time") }
         }
         if self.version < 1 { throw ContractValidationError(field: "version", code: "minimum") }
+        if let value = self.requestedDisplayMode {
+            try value.validate()
+        }
+        if let value = self.effectiveDisplayMode {
+            try value.validate()
+        }
     }
 
     public static func decodeJSON(_ data: Data) throws -> Self { try JSONDecoder().decode(Self.self, from: data) }
@@ -632,6 +644,43 @@ public struct DeviceRegistrationRequest: Codable, Equatable {
     public func encodeJSON() throws -> Data { try validate(); return try JSONEncoder().encode(self) }
 }
 
+public struct DisplayMode: Codable, Equatable {
+    public let resolutionWidth: Int64
+    public let resolutionHeight: Int64
+    public let fps: Int64
+    enum CodingKeys: String, CodingKey {
+        case resolutionWidth = "resolution_width"
+        case resolutionHeight = "resolution_height"
+        case fps = "fps"
+    }
+
+    public init(resolutionWidth: Int64, resolutionHeight: Int64, fps: Int64) throws {
+        self.resolutionWidth = resolutionWidth
+        self.resolutionHeight = resolutionHeight
+        self.fps = fps
+        try validate()
+    }
+
+    public init(from decoder: Decoder) throws {
+        let all = try decoder.container(keyedBy: AnyCodingKey.self)
+        for key in all.allKeys where CodingKeys(stringValue: key.stringValue) == nil { throw ContractValidationError(field: key.stringValue, code: "unknown_field") }
+        let c = try decoder.container(keyedBy: CodingKeys.self)
+        try self.init(resolutionWidth: try c.decode(Int64.self, forKey: .resolutionWidth), resolutionHeight: try c.decode(Int64.self, forKey: .resolutionHeight), fps: try c.decode(Int64.self, forKey: .fps))
+    }
+
+    public func validate() throws {
+        if self.resolutionWidth < 320 { throw ContractValidationError(field: "resolution_width", code: "minimum") }
+        if self.resolutionWidth > 16384 { throw ContractValidationError(field: "resolution_width", code: "maximum") }
+        if self.resolutionHeight < 200 { throw ContractValidationError(field: "resolution_height", code: "minimum") }
+        if self.resolutionHeight > 8640 { throw ContractValidationError(field: "resolution_height", code: "maximum") }
+        if self.fps < 1 { throw ContractValidationError(field: "fps", code: "minimum") }
+        if self.fps > 240 { throw ContractValidationError(field: "fps", code: "maximum") }
+    }
+
+    public static func decodeJSON(_ data: Data) throws -> Self { try JSONDecoder().decode(Self.self, from: data) }
+    public func encodeJSON() throws -> Data { try validate(); return try JSONEncoder().encode(self) }
+}
+
 public struct EntitledPool: Codable, Equatable {
     public let poolId: String
     public let name: String
@@ -1414,14 +1463,17 @@ public struct ManifestGateway: Codable, Equatable {
 public struct ManifestProfile: Codable, Equatable {
     public let id: String
     public let bounds: ManifestBounds
+    public let displayMode: DisplayMode?
     enum CodingKeys: String, CodingKey {
         case id = "id"
         case bounds = "bounds"
+        case displayMode = "display_mode"
     }
 
-    public init(id: String, bounds: ManifestBounds) throws {
+    public init(id: String, bounds: ManifestBounds, displayMode: DisplayMode?) throws {
         self.id = id
         self.bounds = bounds
+        self.displayMode = displayMode
         try validate()
     }
 
@@ -1429,7 +1481,7 @@ public struct ManifestProfile: Codable, Equatable {
         let all = try decoder.container(keyedBy: AnyCodingKey.self)
         for key in all.allKeys where CodingKeys(stringValue: key.stringValue) == nil { throw ContractValidationError(field: key.stringValue, code: "unknown_field") }
         let c = try decoder.container(keyedBy: CodingKeys.self)
-        try self.init(id: try c.decode(String.self, forKey: .id), bounds: try c.decode(ManifestBounds.self, forKey: .bounds))
+        try self.init(id: try c.decode(String.self, forKey: .id), bounds: try c.decode(ManifestBounds.self, forKey: .bounds), displayMode: try c.contains(.displayMode) ? c.decode(DisplayMode.self, forKey: .displayMode) : nil)
     }
 
     public func validate() throws {
@@ -1437,6 +1489,9 @@ public struct ManifestProfile: Codable, Equatable {
         if !self.id.isEmpty && self.id.utf8.count < 1 { throw ContractValidationError(field: "id", code: "min_length") }
         if self.id.utf8.count > 128 { throw ContractValidationError(field: "id", code: "max_length") }
         try self.bounds.validate()
+        if let value = self.displayMode {
+            try value.validate()
+        }
     }
 
     public static func decodeJSON(_ data: Data) throws -> Self { try JSONDecoder().decode(Self.self, from: data) }
@@ -2132,20 +2187,23 @@ public struct SessionRequest: Codable, Equatable {
     public let poolId: String
     public let idempotencyKey: String
     public let policySnapshot: AllocationPolicy
+    public let requestedDisplayMode: DisplayMode?
     enum CodingKeys: String, CodingKey {
         case clientDeviceId = "client_device_id"
         case deviceKeyId = "device_key_id"
         case poolId = "pool_id"
         case idempotencyKey = "idempotency_key"
         case policySnapshot = "policy_snapshot"
+        case requestedDisplayMode = "requested_display_mode"
     }
 
-    public init(clientDeviceId: String, deviceKeyId: String, poolId: String, idempotencyKey: String, policySnapshot: AllocationPolicy) throws {
+    public init(clientDeviceId: String, deviceKeyId: String, poolId: String, idempotencyKey: String, policySnapshot: AllocationPolicy, requestedDisplayMode: DisplayMode?) throws {
         self.clientDeviceId = clientDeviceId
         self.deviceKeyId = deviceKeyId
         self.poolId = poolId
         self.idempotencyKey = idempotencyKey
         self.policySnapshot = policySnapshot
+        self.requestedDisplayMode = requestedDisplayMode
         try validate()
     }
 
@@ -2153,7 +2211,7 @@ public struct SessionRequest: Codable, Equatable {
         let all = try decoder.container(keyedBy: AnyCodingKey.self)
         for key in all.allKeys where CodingKeys(stringValue: key.stringValue) == nil { throw ContractValidationError(field: key.stringValue, code: "unknown_field") }
         let c = try decoder.container(keyedBy: CodingKeys.self)
-        try self.init(clientDeviceId: try c.decode(String.self, forKey: .clientDeviceId), deviceKeyId: try c.decode(String.self, forKey: .deviceKeyId), poolId: try c.decode(String.self, forKey: .poolId), idempotencyKey: try c.decode(String.self, forKey: .idempotencyKey), policySnapshot: try c.decode(AllocationPolicy.self, forKey: .policySnapshot))
+        try self.init(clientDeviceId: try c.decode(String.self, forKey: .clientDeviceId), deviceKeyId: try c.decode(String.self, forKey: .deviceKeyId), poolId: try c.decode(String.self, forKey: .poolId), idempotencyKey: try c.decode(String.self, forKey: .idempotencyKey), policySnapshot: try c.decode(AllocationPolicy.self, forKey: .policySnapshot), requestedDisplayMode: try c.contains(.requestedDisplayMode) ? c.decode(DisplayMode.self, forKey: .requestedDisplayMode) : nil)
     }
 
     public func validate() throws {
@@ -2170,6 +2228,9 @@ public struct SessionRequest: Codable, Equatable {
         if !self.idempotencyKey.isEmpty && self.idempotencyKey.utf8.count < 1 { throw ContractValidationError(field: "idempotency_key", code: "min_length") }
         if self.idempotencyKey.utf8.count > 256 { throw ContractValidationError(field: "idempotency_key", code: "max_length") }
         try self.policySnapshot.validate()
+        if let value = self.requestedDisplayMode {
+            try value.validate()
+        }
     }
 
     public static func decodeJSON(_ data: Data) throws -> Self { try JSONDecoder().decode(Self.self, from: data) }

openspec/changes/archive/2026-08-10-complete-encoded-frame-transport/tasks.md

@@ -15,4 +15,6 @@
 
 ## 4. Immutable boundary
 
-- [ ] 4.1 Publish one new never-reused immutable Protocol version and resolve it from empty consumer caches
+- [x] 4.1 Publish one new never-reused immutable Protocol version, resolve it
+  from separate empty consumer caches, and pin the fetched checksums in both
+  consumers

openspec/changes/phase-3d-client-display-input/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-10

openspec/changes/phase-3d-client-display-input/design.md

@@ -0,0 +1,54 @@
+## Context
+
+The JSON control schema is the generated-binding authority for broker requests
+and manifests, while VGI1 is the provider-neutral input payload. Both contracts
+are strict: old decoders reject unknown response fields and old gateways reject
+unknown VGI kinds. Phase 3D therefore needs optional fields plus explicit
+feature negotiation rather than a wire-version or protobuf change.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Preserve legacy JSON shapes when display negotiation is absent.
+- Generate optional referenced objects correctly in Go, Rust, and Swift.
+- Define exact, bounded, cross-language absolute-pointer and scroll bytes.
+
+**Non-Goals:**
+
+- Server clamp policy, database persistence, or provider translation.
+- Live display renegotiation, provider packet exposure, or protobuf changes.
+
+## Decisions
+
+- Keep control wire version 1 and gate additions with exact feature IDs. This
+  avoids changing every legacy request while allowing strict clients to demand
+  the accepted display field.
+- Use one reusable `DisplayMode` with the existing provider-policy dimension
+  bounds. Optional referenced objects become Go pointers so `omitempty` is real;
+  Rust and Swift retain their existing optional generation.
+- Encode absolute pointer as four big-endian u16 values and scroll as two
+  big-endian i16 values in VGI1. Viewport coordinates are self-contained and
+  provider-neutral; provider scaling stays outside Protocol.
+- Leave protobuf unchanged because the observed broker and VGI consumers use
+  JSON and fixed byte frames, not generated protobuf messages.
+
+## Risks / Trade-offs
+
+- [Old strict consumers reject new response fields] → emit them only after
+  `display.request.v1` negotiation.
+- [New VGI kinds reach an old or unadvertised gateway] → reject before provider
+  translation unless the matching input feature is active.
+- [Generated Go optional values serialize as zero objects] → require pointers,
+  omission tests, and clean second generation.
+
+## Migration Plan
+
+Freeze a new never-reused Protocol RC after full verification. Server and Data
+Plane then pin that exact tag together. Legacy sessions omit all new fields and
+continue using existing input kinds.
+
+## Open Questions
+
+None at the Protocol boundary; policy clamp and Apollo translation remain
+consumer-owned work.

openspec/changes/phase-3d-client-display-input/proposal.md

@@ -0,0 +1,38 @@
+## Why
+
+The Phase 3D native client must request a bounded display mode and send
+provider-neutral absolute-pointer and high-resolution scroll input. The current
+wire contract exposes only policy-selected stream dimensions and rejects both
+new input kinds.
+
+## What Changes
+
+- Add one bounded `DisplayMode` object and optional display fields to session
+  request/session/manifest contracts while keeping control wire version 1.
+- Register `display.request.v1`, `input.absolute.v1`, and `input.scroll.v1` so
+  every new behavior is explicitly negotiated.
+- Extend VGI1 with exact absolute-pointer and signed scroll bodies while
+  preserving all existing kind encodings.
+- Require a new immutable Protocol release candidate after deterministic
+  Go/Rust/Swift generation and conformance pass; existing tags remain unchanged.
+
+## Capabilities
+
+### New Capabilities
+
+- `session-display-mode`: Optional feature-gated requested and effective display
+  mode disclosure for native session creation and manifests.
+
+### Modified Capabilities
+
+- `gateway-input-feedback`: Add negotiated provider-neutral absolute-pointer and
+  high-resolution scroll kinds to the existing sequenced input grammar.
+
+## Impact
+
+- JSON Schema, feature registry, VGI frame documentation, fixed conformance
+  fixtures, generated Go/Rust/Swift bindings, and strict validators.
+- Connection Server session persistence/allocation and Data Plane input
+  translation after consumers pin the immutable Protocol candidate.
+- Protobuf remains unchanged because no observed consumer uses it for these
+  JSON control or VGI payload paths.

openspec/changes/phase-3d-client-display-input/specs/gateway-input-feedback/spec.md

@@ -0,0 +1,33 @@
+## MODIFIED Requirements
+
+### Requirement: Typed sequenced input envelope
+The `input.sequenced.v1` payload SHALL begin with ASCII `VGI1`, a one-byte
+event kind, and one-byte payload length. It SHALL contain exactly one bounded
+keyboard, mouse-button, relative-mouse, UTF-8 scalar, controller-state,
+absolute-mouse, or high-resolution-scroll event. Absolute mouse kind `0x06`
+SHALL contain big-endian u16 x, y, viewport width, and viewport height, reject
+zero viewports and coordinates outside the viewport, and require negotiated
+`input.absolute.v1`. Scroll kind `0x07` SHALL contain big-endian signed i16
+vertical and horizontal deltas and require negotiated `input.scroll.v1`. False
+keyboard/mouse state and zeroed controller state are explicit releases.
+Unknown or unadvertised kinds, length mismatches, malformed UTF-8, unsupported
+controller indices, and reserved fields SHALL be rejected before provider
+translation.
+
+#### Scenario: Keyboard state change
+- **WHEN** a client sends a valid keyboard press or release envelope
+- **THEN** the gateway forwards the corresponding typed provider input on its
+  reliable keyboard channel and records the pressed state for cleanup.
+
+#### Scenario: Absolute pointer and scroll
+- **WHEN** an advertised client sends an in-viewport absolute coordinate or
+  signed scroll delta with the exact body length
+- **THEN** the gateway accepts the provider-neutral event without adding it to
+  pressed-state cleanup.
+
+#### Scenario: Invalid input envelope
+- **WHEN** a client sends an unknown or unadvertised kind, invalid length,
+  malformed UTF-8 scalar, zero viewport, out-of-range coordinate, or nonzero
+  reserved field
+- **THEN** the gateway rejects it without sending provider input or changing
+  pressed state.

openspec/changes/phase-3d-client-display-input/specs/session-display-mode/spec.md

@@ -0,0 +1,35 @@
+## ADDED Requirements
+
+### Requirement: Bounded display mode contract
+The Protocol SHALL define `DisplayMode` with required integer
+`resolution_width` from 320 through 16384, `resolution_height` from 200 through
+8640, and `fps` from 1 through 240, rejecting missing, unknown, or out-of-range
+fields.
+
+#### Scenario: Valid display mode
+- **WHEN** a client encodes a 2560 by 1440 display mode at 120 FPS
+- **THEN** generated Go, Rust, and Swift bindings accept the same exact values.
+
+#### Scenario: Invalid display mode
+- **WHEN** any dimension or FPS is outside its bound or an unknown field exists
+- **THEN** strict Protocol validation rejects the object.
+
+### Requirement: Feature-gated optional display disclosure
+`SessionRequest.requested_display_mode`,
+`BrokerSession.requested_display_mode`,
+`BrokerSession.effective_display_mode`, and `ManifestProfile.display_mode`
+SHALL be optional references to `DisplayMode`. Go bindings SHALL use pointers
+with JSON omission and Rust/Swift bindings SHALL use optionals. A client MUST
+send the request only after `display.request.v1` negotiation, and a
+display-aware manifest MUST contain the accepted mode. Legacy requests SHALL
+produce legacy response shapes without these fields.
+
+#### Scenario: Legacy request remains unchanged
+- **WHEN** a client omits `requested_display_mode`
+- **THEN** encoding omits the field and compatible Server responses omit all
+  display-mode fields.
+
+#### Scenario: Display-aware request discloses acceptance
+- **WHEN** a negotiated client sends a valid requested mode
+- **THEN** session responses preserve the requested mode and the allocated
+  manifest includes the Server-accepted mode.

openspec/changes/phase-3d-client-display-input/tasks.md

@@ -0,0 +1,17 @@
+## 1. Contract sources
+
+- [x] 1.1 Add failing Go omission/bounds tests and fixed absolute/scroll vectors.
+- [x] 1.2 Add the bounded display schema, optional generated references, and feature registrations.
+- [x] 1.3 Extend the VGI frame grammar and Python/Go/Rust/Swift classifiers without changing existing kinds.
+
+## 2. Deterministic verification
+
+- [x] 2.1 Regenerate Go/Rust/Swift bindings and pass focused Go, frame, source, binding, and strict-contract checks.
+- [x] 2.2 Run the complete Protocol verifier with isolated compiler caches.
+- [x] 2.3 Regenerate a second time, confirm zero drift, and inspect the exact source/generated diff.
+
+## 3. Freeze
+
+- [ ] 3.1 Commit the verified source and generated bindings as one unsigned capability-sized change.
+- [ ] 3.2 Verify the next Phase 3D Protocol RC name is unused locally and remotely, then create one local immutable candidate tag without publishing it.
+- [ ] 3.3 Reconcile and archive this OpenSpec change after the immutable candidate is frozen.

openspec/specs/gateway-media-framing/spec.md

@@ -0,0 +1,37 @@
+# gateway-media-framing Specification
+
+## Purpose
+Define the versioned datagram framing, bounded reassembly, and explicit negotiation required to carry complete encoded media units.
+## Requirements
+### Requirement: Versioned complete encoded-frame datagrams
+The Protocol SHALL register `datagram-v2` with a 23-byte network-order header containing magic, version, channel, flags, sequence, timestamp, unsigned 16-bit fragment index, unsigned 16-bit fragment count, and unsigned 16-bit payload length. Media datagrams MUST remain at most 1,200 bytes with at most 1,177 payload bytes, and one sequence MUST represent exactly one complete encoded unit of at most 1,048,576 bytes and 891 fragments.
+
+#### Scenario: Bounded large encoded frame
+- **WHEN** an encoded media frame is larger than the datagram-v1 18,864-byte limit but no larger than 1,048,576 bytes
+- **THEN** datagram-v2 carries it under one sequence in at most 891 independently bounded fragments
+
+#### Scenario: Oversized encoded frame
+- **WHEN** a sender attempts more than 1,048,576 complete bytes or 891 fragments
+- **THEN** framing rejects the unit before sending or allocating proportional state
+
+### Requirement: Bounded complete-frame reassembly
+Datagram-v2 reassembly SHALL retain at most four incomplete media units and only the bytes actually received, permit bounded fragment reorder and exact duplicate fragments, reject conflicting duplicates or inconsistent metadata, expire incomplete state after 250 milliseconds, and emit a payload only after every fragment is present exactly once.
+
+#### Scenario: Reordered frame completes
+- **WHEN** every valid fragment for one unit arrives out of order within the reassembly bounds
+- **THEN** the receiver emits exactly one byte-identical complete encoded frame with its original boundary
+
+#### Scenario: Malformed or stale reassembly
+- **WHEN** fragments conflict, metadata changes, an index or count is invalid, state exceeds four incomplete units, or a unit exceeds its timeout
+- **THEN** the receiver rejects or evicts that incomplete unit without proportional allocation or payload emission
+
+### Requirement: Explicit framing negotiation
+`CapabilityProfile.framing` SHALL accept only registered `datagram-v1` or `datagram-v2` values. A peer MUST use datagram-v2 only after exact capability intersection and MUST NOT reinterpret datagram-v1 bytes as datagram-v2.
+
+#### Scenario: Independent datagram-v2 peers overlap
+- **WHEN** both peers advertise the registered datagram-v2 framing profile
+- **THEN** generated Go, Rust, and Swift validation and fixed conformance accept the profile
+
+#### Scenario: Unknown or downgraded framing
+- **WHEN** a peer advertises an unknown framing value or the peers advertise different versions
+- **THEN** capability validation or intersection rejects the session before media forwarding

registries/features.json

@@ -3,6 +3,9 @@
   "features": [
     {"id": "control.v1", "direction": "bidirectional", "max_frame_bytes": 65536},
     {"id": "events.resume.v1", "direction": "server-to-client", "max_frame_bytes": 65536},
-    {"id": "clipboard.text.v1", "direction": "bidirectional", "max_frame_bytes": 65536}
+    {"id": "clipboard.text.v1", "direction": "bidirectional", "max_frame_bytes": 65536},
+    {"id": "display.request.v1", "direction": "client-to-server", "max_frame_bytes": 65536},
+    {"id": "input.absolute.v1", "direction": "client-to-server", "max_frame_bytes": 14},
+    {"id": "input.scroll.v1", "direction": "client-to-server", "max_frame_bytes": 10}
   ]
 }

schemas/control-v1.schema.json

@@ -178,6 +178,16 @@
         "refresh_expires_at": {"type": "string", "format": "date-time", "maxLength": 64}
       }
     },
+    "DisplayMode": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["resolution_width", "resolution_height", "fps"],
+      "properties": {
+        "resolution_width": {"type": "integer", "minimum": 320, "maximum": 16384},
+        "resolution_height": {"type": "integer", "minimum": 200, "maximum": 8640},
+        "fps": {"type": "integer", "minimum": 1, "maximum": 240}
+      }
+    },
     "SessionRequest": {
       "type": "object",
       "additionalProperties": false,
@@ -187,7 +197,8 @@
         "device_key_id": {"type": "string", "minLength": 1, "maxLength": 128},
         "pool_id": {"type": "string", "minLength": 1, "maxLength": 128},
         "idempotency_key": {"type": "string", "minLength": 1, "maxLength": 256},
-        "policy_snapshot": {"$ref": "#/$defs/AllocationPolicy"}
+        "policy_snapshot": {"$ref": "#/$defs/AllocationPolicy"},
+        "requested_display_mode": {"$ref": "#/$defs/DisplayMode"}
       }
     },
     "ReconnectRequest": {
@@ -219,7 +230,9 @@
         "correlation_id": {"type": "string", "minLength": 1, "maxLength": 128},
         "requested_at": {"type": "string", "format": "date-time", "maxLength": 64},
         "ended_at": {"type": "string", "format": "date-time", "maxLength": 64},
-        "version": {"type": "integer", "minimum": 1}
+        "version": {"type": "integer", "minimum": 1},
+        "requested_display_mode": {"$ref": "#/$defs/DisplayMode"},
+        "effective_display_mode": {"$ref": "#/$defs/DisplayMode"}
       }
     },
     "AllocationPolicy": {
@@ -279,7 +292,8 @@
       "required": ["id", "bounds"],
       "properties": {
         "id": {"type": "string", "minLength": 1, "maxLength": 128},
-        "bounds": {"$ref": "#/$defs/ManifestBounds"}
+        "bounds": {"$ref": "#/$defs/ManifestBounds"},
+        "display_mode": {"$ref": "#/$defs/DisplayMode"}
       }
     },
     "ManifestBounds": {

tests/go/protocol_test.go

@@ -1,6 +1,7 @@
 package protocol_test
 
 import (
+	"bytes"
 	"reflect"
 	"strings"
 	"testing"
@@ -22,6 +23,83 @@ func TestManifestRejectsForbiddenAndUnknownFields(t *testing.T) {
 	}
 }
 
+func TestDisplayModeIsOptionalStrictAndBounded(t *testing.T) {
+	displayType := reflect.TypeOf(protocol.DisplayMode{})
+	for _, field := range []struct {
+		owner reflect.Type
+		name  string
+	}{
+		{reflect.TypeOf(protocol.SessionRequest{}), "RequestedDisplayMode"},
+		{reflect.TypeOf(protocol.BrokerSession{}), "RequestedDisplayMode"},
+		{reflect.TypeOf(protocol.BrokerSession{}), "EffectiveDisplayMode"},
+		{reflect.TypeOf(protocol.ManifestProfile{}), "DisplayMode"},
+	} {
+		actual, ok := field.owner.FieldByName(field.name)
+		if !ok || actual.Type.Kind() != reflect.Pointer || actual.Type.Elem() != displayType {
+			t.Fatalf("%s.%s must be *DisplayMode, got %v", field.owner, field.name, actual.Type)
+		}
+	}
+
+	request := protocol.SessionRequest{
+		ClientDeviceID: "device-1", DeviceKeyID: "key-1", PoolID: "pool-1", IdempotencyKey: "request-1",
+		PolicySnapshot: protocol.AllocationPolicy{
+			MinimumKbps: 1000, TargetKbps: 2000, MaximumKbps: 3000, Tier: "standard",
+			Audience: "versevdi-gateway", Protocol: "verse", ProtocolVersion: 1,
+			GrantTTLSeconds: 60, ReservationLeaseSeconds: 300,
+		},
+	}
+	legacy, err := protocol.EncodeSessionRequest(request)
+	if err != nil {
+		t.Fatalf("EncodeSessionRequest legacy request: %v", err)
+	}
+	if bytes.Contains(legacy, []byte("requested_display_mode")) {
+		t.Fatalf("legacy request disclosed an absent display mode: %s", legacy)
+	}
+
+	mode := protocol.DisplayMode{ResolutionWidth: 2560, ResolutionHeight: 1440, Fps: 120}
+	request.RequestedDisplayMode = &mode
+	aware, err := protocol.EncodeSessionRequest(request)
+	if err != nil || !bytes.Contains(aware, []byte(`"requested_display_mode":{"resolution_width":2560,"resolution_height":1440,"fps":120}`)) {
+		t.Fatalf("display-aware request = %s, err = %v", aware, err)
+	}
+	decoded, err := protocol.DecodeSessionRequest(aware)
+	if err != nil || decoded.RequestedDisplayMode == nil || *decoded.RequestedDisplayMode != mode {
+		t.Fatalf("DecodeSessionRequest display mode = %+v, err = %v", decoded.RequestedDisplayMode, err)
+	}
+	nullMode := bytes.Replace(aware, []byte(`{"resolution_width":2560,"resolution_height":1440,"fps":120}`), []byte("null"), 1)
+	if _, err := protocol.DecodeSessionRequest(nullMode); err == nil {
+		t.Fatalf("DecodeSessionRequest accepted explicit null display mode: %s", nullMode)
+	}
+
+	profile := protocol.ManifestProfile{
+		ID:     "standard",
+		Bounds: protocol.ManifestBounds{MinimumKbps: 1000, TargetKbps: 2000, MaximumKbps: 3000},
+	}
+	legacyProfile, err := protocol.EncodeManifestProfile(profile)
+	if err != nil || bytes.Contains(legacyProfile, []byte("display_mode")) {
+		t.Fatalf("legacy profile = %s, err = %v", legacyProfile, err)
+	}
+	profile.DisplayMode = &mode
+	awareProfile, err := protocol.EncodeManifestProfile(profile)
+	if err != nil || !bytes.Contains(awareProfile, []byte(`"display_mode":{"resolution_width":2560,"resolution_height":1440,"fps":120}`)) {
+		t.Fatalf("display-aware profile = %s, err = %v", awareProfile, err)
+	}
+
+	for _, invalid := range []string{
+		`{"resolution_width":319,"resolution_height":1440,"fps":120}`,
+		`{"resolution_width":16385,"resolution_height":1440,"fps":120}`,
+		`{"resolution_width":2560,"resolution_height":199,"fps":120}`,
+		`{"resolution_width":2560,"resolution_height":8641,"fps":120}`,
+		`{"resolution_width":2560,"resolution_height":1440,"fps":0}`,
+		`{"resolution_width":2560,"resolution_height":1440,"fps":241}`,
+		`{"resolution_width":2560,"resolution_height":1440,"fps":120,"unknown":true}`,
+	} {
+		if _, err := protocol.DecodeDisplayMode([]byte(invalid)); err == nil {
+			t.Fatalf("DecodeDisplayMode accepted %s", invalid)
+		}
+	}
+}
+
 func TestPageInfoRejectsOutOfBoundsLimit(t *testing.T) {
 	if _, err := protocol.DecodePageInfo([]byte(`{"limit":101,"next_cursor":""}`)); err == nil {
 		t.Fatal("DecodePageInfo accepted limit above the contract maximum")

tools/generate.py

@@ -160,7 +160,11 @@ def go_validation(definition: dict[str, Any]) -> list[str]:
                 lines.append(f"\tfor index := range v.{field} {{ if err := v.{field}[index].Validate(); err != nil {{ violations = append(violations, FieldViolation{{Field: fmt.Sprintf(\"{prop_name}[%d]\", index), Code: \"invalid_item\"}}) }} }}")
         reference = ref_name(prop)
         if reference:
-            lines.append(f"\tif err := v.{field}.Validate(); err != nil {{ violations = append(violations, FieldViolation{{Field: \"{prop_name}\", Code: \"invalid_object\"}}) }}")
+            validation = f"if err := v.{field}.Validate(); err != nil {{ violations = append(violations, FieldViolation{{Field: \"{prop_name}\", Code: \"invalid_object\"}}) }}"
+            if prop_name not in required:
+                lines.append(f"\tif v.{field} != nil {{ {validation} }}")
+            else:
+                lines.append(f"\t{validation}")
     if name in {"AllocationPolicy", "ManifestBounds"}:
         lines.append("\tif v.MinimumKbps > v.TargetKbps || v.TargetKbps > v.MaximumKbps { violations = append(violations, FieldViolation{Field: \"bounds\", Code: \"invalid_order\"}) }")
     if name == "GatewayRegistration":
@@ -212,7 +216,10 @@ def generate_go(defs: dict[str, dict[str, Any]], schema_hash: str, version: str,
         required = set(definition.get("required", []))
         for prop_name, prop in definition.get("properties", {}).items():
             tag = prop_name + (",omitempty" if prop_name not in required else "")
-            out.append(f"\t{go_field(prop_name)} {prop_type(prop, 'go')} `json:\"{tag}\"`")
+            typ = prop_type(prop, "go")
+            if prop_name not in required and ref_name(prop):
+                typ = "*" + typ
+            out.append(f"\t{go_field(prop_name)} {typ} `json:\"{tag}\"`")
         out.extend(["}", ""])
     for name in sorted(defs):
         out.append(f"func (v {name}) Validate() error {{")
@@ -234,6 +241,11 @@ def generate_go(defs: dict[str, dict[str, Any]], schema_hash: str, version: str,
                 % (prop_name, prop_name)
             )
         for prop_name, prop in defs[name].get("properties", {}).items():
+            if prop_name not in required_fields and ref_name(prop):
+                out.append(
+                    '\tif raw, ok := fields["%s"]; ok && bytes.Equal(bytes.TrimSpace(raw), []byte("null")) { return value, ValidationError{Violations: []FieldViolation{{Field: "%s", Code: "invalid_object"}}} }'
+                    % (prop_name, prop_name)
+                )
             if "x-max-bytes" in prop and prop.get("type") != "string":
                 out.append(
                     '\tif raw, ok := fields["%s"]; ok && len(raw) > %d { return value, ValidationError{Violations: []FieldViolation{{Field: "%s", Code: "max_bytes"}}} }'
@@ -603,6 +615,8 @@ def generate_swift(defs: dict[str, dict[str, Any]], schema_hash: str, compatibil
             typ = swift_type(prop)
             if prop_name in required:
                 decoded.append(f"{field}: try c.decode({typ}.self, forKey: .{field})")
+            elif ref_name(prop):
+                decoded.append(f"{field}: try c.contains(.{field}) ? c.decode({typ}.self, forKey: .{field}) : nil")
             else:
                 decoded.append(f"{field}: try c.decodeIfPresent({typ}.self, forKey: .{field})")
         out.append(f"        try self.init({', '.join(decoded)})")

tools/go-conformance/main.go

@@ -125,10 +125,12 @@ func evaluate(kind, input string) string {
 		}
 		return "valid"
 	case "tunnel":
-		if (parts["offered"] == "1" || parts["offered"] == "0" || parts["offered"] == "-1") && parts["feature"] == "control.v1" {
+		feature := parts["feature"]
+		registered := feature == "control.v1" || feature == "display.request.v1" || feature == "input.absolute.v1" || feature == "input.scroll.v1"
+		if (parts["offered"] == "1" || parts["offered"] == "0" || parts["offered"] == "-1") && registered {
 			return "valid"
 		}
-		if parts["feature"] != "control.v1" {
+		if !registered {
 			return "invalid:unsupported_feature"
 		}
 		return "invalid:unsupported_version"
@@ -226,6 +228,19 @@ func classifyGatewayInput(encoded string) string {
 				}
 			}
 		}
+	case 6:
+		if len(body) != 8 {
+			return "invalid:length"
+		}
+		x, y := uint16(body[0])<<8|uint16(body[1]), uint16(body[2])<<8|uint16(body[3])
+		width, height := uint16(body[4])<<8|uint16(body[5]), uint16(body[6])<<8|uint16(body[7])
+		if width == 0 || height == 0 || x >= width || y >= height {
+			return "invalid:field"
+		}
+	case 7:
+		if len(body) != 4 {
+			return "invalid:length"
+		}
 	default:
 		return "invalid:kind"
 	}

tools/native_conformance.rs

@@ -47,8 +47,8 @@ fn evaluate(kind: &str, input: &str) -> &'static str {
             || !values.contains_key("correlation_id") => "invalid:required",
         "event" => "valid",
         "tunnel" if matches!(values.get("offered").map(String::as_str), Some("1") | Some("0") | Some("-1"))
-            && values.get("feature").map(String::as_str) == Some("control.v1") => "valid",
+            && matches!(values.get("feature").map(String::as_str), Some("control.v1") | Some("display.request.v1") | Some("input.absolute.v1") | Some("input.scroll.v1")) => "valid",
-        "tunnel" if values.get("feature").map(String::as_str) != Some("control.v1") => {
+        "tunnel" if !matches!(values.get("feature").map(String::as_str), Some("control.v1") | Some("display.request.v1") | Some("input.absolute.v1") | Some("input.scroll.v1")) => {
             "invalid:unsupported_feature"
         }
         "tunnel" => "invalid:unsupported_version",
@@ -110,6 +110,16 @@ fn classify_gateway_input(encoded: &str) -> &'static str {
         5 if body[0] > 15 => "invalid:field",
         5 if body[1] == 0 && body[2] == 0 && body[3..].iter().any(|value| *value != 0) => "invalid:field",
         5 => "valid",
+        6 if body.len() != 8 => "invalid:length",
+        6 => {
+            let x = u16::from_be_bytes([body[0], body[1]]);
+            let y = u16::from_be_bytes([body[2], body[3]]);
+            let width = u16::from_be_bytes([body[4], body[5]]);
+            let height = u16::from_be_bytes([body[6], body[7]]);
+            if width != 0 && height != 0 && x < width && y < height { "valid" } else { "invalid:field" }
+        }
+        7 if body.len() == 4 => "valid",
+        7 => "invalid:length",
         _ => "invalid:kind",
     }
 }

tools/native_conformance.swift

@@ -27,8 +27,9 @@ func evaluate(_ kind: String, _ input: String) -> String {
         guard let sequence = Int(values["sequence"] ?? ""), sequence > 0, values["correlation_id"] != nil else { return "invalid:required" }
         return "valid"
     case "tunnel":
-        if ["1", "0", "-1"].contains(values["offered"] ?? "") && values["feature"] == "control.v1" { return "valid" }
+        let registered = ["control.v1", "display.request.v1", "input.absolute.v1", "input.scroll.v1"].contains(values["feature"] ?? "")
-        return values["feature"] == "control.v1" ? "invalid:unsupported_version" : "invalid:unsupported_feature"
+        if ["1", "0", "-1"].contains(values["offered"] ?? "") && registered { return "valid" }
+        return registered ? "invalid:unsupported_version" : "invalid:unsupported_feature"
     case "datagram": return classifyDatagram(values["hex"] ?? "")
     case "gateway_input": return classifyGatewayInput(values["hex"] ?? "")
     case "gateway_feedback": return classifyGatewayFeedback(values["hex"] ?? "")
@@ -82,6 +83,14 @@ func classifyGatewayInput(_ encoded: String) -> String {
         guard body[0] <= 15 else { return "invalid:field" }
         guard body[1] != 0 || body[2] != 0 || body.dropFirst(3).allSatisfy({ $0 == 0 }) else { return "invalid:field" }
         return "valid"
+    case 6:
+        guard body.count == 8 else { return "invalid:length" }
+        let x = Int(body[0]) * 256 + Int(body[1])
+        let y = Int(body[2]) * 256 + Int(body[3])
+        let width = Int(body[4]) * 256 + Int(body[5])
+        let height = Int(body[6]) * 256 + Int(body[7])
+        return width > 0 && height > 0 && x < width && y < height ? "valid" : "invalid:field"
+    case 7: return body.count == 4 ? "valid" : "invalid:length"
     default: return "invalid:kind"
     }
 }

tools/test_generated_contracts.py

@@ -103,6 +103,44 @@ do {
     )
     fatalError("invalid allocation bounds were accepted")
 } catch { }
+let displayMode = try DisplayMode(resolutionWidth: 2560, resolutionHeight: 1440, fps: 120)
+for invalid in [
+    { try DisplayMode(resolutionWidth: 319, resolutionHeight: 1440, fps: 120) },
+    { try DisplayMode(resolutionWidth: 2560, resolutionHeight: 199, fps: 120) },
+    { try DisplayMode(resolutionWidth: 2560, resolutionHeight: 1440, fps: 241) },
+] {
+    do {
+        _ = try invalid()
+        fatalError("invalid display mode was accepted")
+    } catch { }
+}
+let allocationPolicy = try AllocationPolicy(
+    minimumKbps: 1000, targetKbps: 2000, maximumKbps: 3000, tier: "standard",
+    audience: "versevdi-gateway", protocolValue: "verse", protocolVersion: 1,
+    grantTtlSeconds: 60, reservationLeaseSeconds: 300
+)
+let legacyDisplayRequest = try SessionRequest(
+    clientDeviceId: "device-1", deviceKeyId: "key-1", poolId: "pool-1",
+    idempotencyKey: "request-1", policySnapshot: allocationPolicy,
+    requestedDisplayMode: nil
+).encodeJSON()
+guard !String(data: legacyDisplayRequest, encoding: .utf8)!.contains("requested_display_mode") else {
+    fatalError("legacy request encoded an absent display mode")
+}
+let displayRequest = try SessionRequest(
+    clientDeviceId: "device-1", deviceKeyId: "key-1", poolId: "pool-1",
+    idempotencyKey: "request-1", policySnapshot: allocationPolicy,
+    requestedDisplayMode: displayMode
+)
+guard try SessionRequest.decodeJSON(displayRequest.encodeJSON()).requestedDisplayMode == displayMode else {
+    fatalError("display mode did not round-trip")
+}
+var nullDisplayRequest = try JSONSerialization.jsonObject(with: displayRequest.encodeJSON()) as! [String: Any]
+nullDisplayRequest["requested_display_mode"] = NSNull()
+do {
+    _ = try SessionRequest.decodeJSON(try JSONSerialization.data(withJSONObject: nullDisplayRequest))
+    fatalError("explicit null display mode was accepted")
+} catch { }
 let streamPolicy = try ProviderStreamPolicy(
     resolutionWidth: 2560, resolutionHeight: 1440, fps: 120,
     codec: "HEVC", bitrateKbps: 40000, audioEnabled: true
@@ -218,6 +256,24 @@ fn main() {
     assert!(AllocationPolicy::new(
         100, 50, 25, "standard".into(), "audience".into(), "verse".into(), 1, 60, 300,
     ).is_err());
+    let display_mode = DisplayMode::new(2560, 1440, 120).unwrap();
+    assert!(DisplayMode::new(319, 1440, 120).is_err());
+    assert!(DisplayMode::new(2560, 199, 120).is_err());
+    assert!(DisplayMode::new(2560, 1440, 241).is_err());
+    let allocation_policy = AllocationPolicy::new(
+        1000, 2000, 3000, "standard".into(), "versevdi-gateway".into(),
+        "verse".into(), 1, 60, 300,
+    ).unwrap();
+    let legacy_display_request = SessionRequest::new(
+        "device-1".into(), "key-1".into(), "pool-1".into(), "request-1".into(),
+        allocation_policy.clone(), None,
+    ).unwrap();
+    assert!(legacy_display_request.requestedDisplayMode().is_none());
+    let display_request = SessionRequest::new(
+        "device-1".into(), "key-1".into(), "pool-1".into(), "request-1".into(),
+        allocation_policy, Some(display_mode.clone()),
+    ).unwrap();
+    assert_eq!(display_request.requestedDisplayMode(), &Some(display_mode));
     assert!(ProviderStreamPolicy::new(
         2560, 1440, 120, "HEVC".into(), 40000, true,
     ).is_ok());

tools/validate.py

@@ -36,6 +36,24 @@ def main() -> int:
             maximum = entry.get("max_frame_bytes", entry.get("max_payload_bytes"))
             assert isinstance(maximum, int) and 1 <= maximum <= maximum_bound
 
+    feature_registry = json.loads((ROOT / "registries/features.json").read_text(encoding="utf-8"))
+    registered_features = {entry["id"] for entry in feature_registry["features"]}
+    assert {"display.request.v1", "input.absolute.v1", "input.scroll.v1"}.issubset(registered_features)
+
+    display_mode = defs["DisplayMode"]
+    assert display_mode["required"] == ["resolution_width", "resolution_height", "fps"]
+    assert display_mode["properties"]["resolution_width"] == {"type": "integer", "minimum": 320, "maximum": 16384}
+    assert display_mode["properties"]["resolution_height"] == {"type": "integer", "minimum": 200, "maximum": 8640}
+    assert display_mode["properties"]["fps"] == {"type": "integer", "minimum": 1, "maximum": 240}
+    for owner, field in (
+        ("SessionRequest", "requested_display_mode"),
+        ("BrokerSession", "requested_display_mode"),
+        ("BrokerSession", "effective_display_mode"),
+        ("ManifestProfile", "display_mode"),
+    ):
+        assert field not in defs[owner]["required"]
+        assert defs[owner]["properties"][field] == {"$ref": "#/$defs/DisplayMode"}
+
     manifest = json.loads((ROOT / "fixtures/valid/manifest.json").read_text(encoding="utf-8"))
     assert set(manifest).issubset(set(defs["ConnectionManifest"]["properties"]))
     forbidden = json.loads((ROOT / "fixtures/invalid/manifest-provider-field.json").read_text(encoding="utf-8"))

tools/validate_gateway_envelopes.py

@@ -37,6 +37,13 @@ def classify_input(raw: bytes) -> str:
             return "invalid:field"
         active_mask = int.from_bytes(body[1:3], "big")
         return "valid" if active_mask or not any(body[3:]) else "invalid:field"
+    if kind == 6:
+        if len(body) != 8:
+            return "invalid:length"
+        x, y, width, height = (int.from_bytes(body[index:index + 2], "big") for index in range(0, 8, 2))
+        return "valid" if width and height and x < width and y < height else "invalid:field"
+    if kind == 7:
+        return "valid" if len(body) == 4 else "invalid:length"
     return "invalid:kind"