Major architecture update: stable identity, component validation, media indexing, and protocol docs

lib/models.dart

@@ -16,7 +16,7 @@ class ChatUser {
   @Id()
   int id = 0;
 
-  // Global identifier: "username@homeserver.com"
+  // Global immutable identifier (opaque, host-independent).
   @Unique()
   String userId;
 
@@ -37,8 +37,7 @@ class ChatUser {
 
   // Server relationship
   bool isLocal; // true = this is their home server
-  String?
-      homeServer; // if guest, where is their home? (e.g., "https://my.server.com")
+  String? homeServer; // if guest, where is their home? (e.g., "https://my.server.com")
 
   // Server-specific
   List<String> roles; // ["admin", "moderator", "member"]
@@ -98,7 +97,7 @@ class ChatMessage {
 
   // Author info - includes enough for cross-server profile fetch
   int authorLocalId;
-  String authorUserId; // "alice@homeserver.com"
+  String authorUserId; // Immutable userId
   String? authorHomeServer; // for profile fetching
 
   // Cached for display (snapshot at message time)
@@ -133,25 +132,113 @@ class ChatFile {
   @Id()
   int id = 0;
 
+  @Unique()
+  String attachmentId;
+
   int uploaderId;
   String path;
+  String originalFileName;
+  String storedFileName;
+  String sha256;
   String mimeType;
   int width;
   int height;
   int sizeBytes;
   bool isAttached;
+  String usageType; // message | avatar | server_icon | server_banner
+  String status; // pending | ready | failed
+  String? errorCode;
 
   @Property(type: PropertyType.date)
   DateTime createdAt;
 
   ChatFile({
+    required this.attachmentId,
     required this.uploaderId,
     required this.path,
+    required this.originalFileName,
+    required this.storedFileName,
+    required this.sha256,
     required this.mimeType,
     required this.width,
     required this.height,
     required this.sizeBytes,
+    this.usageType = 'message',
+    this.status = 'pending',
     this.isAttached = false,
+    this.errorCode,
+    DateTime? createdAt,
+  }) : createdAt = createdAt ?? DateTime.now();
+}
+
+@Entity()
+class ServerSettings {
+  @Id()
+  int id = 0;
+
+  @Unique()
+  String singletonKey;
+
+  String serverName;
+  String? description;
+  String? iconAttachmentId;
+  String? bannerAttachmentId;
+  String? updatedByUserId;
+
+  @Property(type: PropertyType.date)
+  DateTime updatedAt;
+
+  ServerSettings({
+    this.singletonKey = 'default',
+    required this.serverName,
+    this.description,
+    this.iconAttachmentId,
+    this.bannerAttachmentId,
+    this.updatedByUserId,
+    DateTime? updatedAt,
+  }) : updatedAt = updatedAt ?? DateTime.now();
+}
+
+@Entity()
+class ChatMessageMedia {
+  @Id()
+  int id = 0;
+
+  int messageId;
+  int channelId;
+  String authorUserId;
+
+  // local_upload
+  String? attachmentId;
+
+  // external_url
+  String? externalUrl;
+
+  // image | video | file
+  String kind;
+  String? mimeType;
+  String? originalFileName;
+  int? sizeBytes;
+  int? width;
+  int? height;
+  String? thumbHash;
+
+  @Property(type: PropertyType.date)
+  DateTime createdAt;
+
+  ChatMessageMedia({
+    required this.messageId,
+    required this.channelId,
+    required this.authorUserId,
+    required this.kind,
+    this.attachmentId,
+    this.externalUrl,
+    this.mimeType,
+    this.originalFileName,
+    this.sizeBytes,
+    this.width,
+    this.height,
+    this.thumbHash,
     DateTime? createdAt,
   }) : createdAt = createdAt ?? DateTime.now();
 }