···

       
390
       
390
       
 
       


     

       
391
       
391
       
 
       
## Technical Decisions Log

     

       
392
       
392
       
 
       


     

       
393
       
393
       
+
       
### 2025-10-18: Moderator Lexicon Extensibility

     

       
394
       
394
       
+
       
**Decision:** Use `knownValues` instead of `enum` for moderator roles and permissions in `social.coves.community.moderator` record schema

     

       
395
       
395
       
+
       


     

       
396
       
396
       
+
       
**Rationale:**

     

       
397
       
397
       
+
       
- Moderator records are immutable once published (atProto record semantics)

     

       
398
       
398
       
+
       
- Closed `enum` values cannot be extended without breaking schema evolution rules

     

       
399
       
399
       
+
       
- Using `knownValues` allows adding new roles/permissions in Beta Phase 2 without requiring V2 schema migration

     

       
400
       
400
       
+
       
- Zero cost to fix during alpha planning; expensive to migrate once records exist in production

     

       
401
       
401
       
+
       


     

       
402
       
402
       
+
       
**Changes Made:**

     

       
403
       
403
       
+
       
- `role` field: Changed from `enum: ["moderator", "admin"]` to `knownValues: ["moderator", "admin"]` with `maxLength: 64`

     

       
404
       
404
       
+
       
- `permissions` array items: Changed from closed enum to `knownValues` with `maxLength: 64`

     

       
405
       
405
       
+
       


     

       
406
       
406
       
+
       
**Future Extensibility Examples:**

     

       
407
       
407
       
+
       
- **New roles**: "owner" (full transfer rights), "trainee" (limited trial moderator), "emeritus" (honorary former moderator)

     

       
408
       
408
       
+
       
- **New permissions**: "manage_bots", "manage_flairs", "manage_automoderator", "manage_federation", "pin_posts"

     

       
409
       
409
       
+
       
- Can add these values during Phase 2 (Moderator Tiers & Permissions) without breaking existing moderator records

     

       
410
       
410
       
+
       


     

       
411
       
411
       
+
       
**atProto Style Guide Reference:**

     

       
412
       
412
       
+
       
Per [atproto#4245](https://github.com/bluesky-social/atproto/discussions/4245): "Enum sets are 'closed' and can not be updated or extended without breaking schema evolution rules. For this reason they should almost always be avoided. For strings, `knownValues` provides more flexible alternative."

     

       
413
       
413
       
+
       


     

       
414
       
414
       
+
       
**Implementation Status:** ✅ Fixed in lexicon before alpha launch

     

       
415
       
415
       
+
       


     

       
416
       
416
       
+
       
---

     

       
417
       
417
       
+
       


     

       
393
       
418
       
 
       
### 2025-10-11: Moderator Records Storage Location

     

       
394
       
419
       
 
       
**Decision:** Store moderator records in community's repository (`at://community_did/social.coves.community.moderator/{tid}`), not user's repository

     

       
395
       
420
       
 
       


     

···

       
22
       
22
       
 
       
          },

     

       
23
       
23
       
 
       
          "role": {

     

       
24
       
24
       
 
       
            "type": "string",

     

       
25
       
25
       
-
       
            "enum": ["moderator", "admin"],

     

       
25
       
25
       
+
       
            "knownValues": ["moderator", "admin"],

     

       
26
       
26
       
+
       
            "maxLength": 64,

     

       
26
       
27
       
 
       
            "description": "Level of moderation privileges"

     

       
27
       
28
       
 
       
          },

     

       
28
       
29
       
 
       
          "permissions": {

     
···

       
30
       
31
       
 
       
            "description": "Specific permissions granted",

     

       
31
       
32
       
 
       
            "items": {

     

       
32
       
33
       
 
       
              "type": "string",

     

       
33
       
33
       
-
       
              "enum": [

     

       
34
       
34
       
+
       
              "knownValues": [

     

       
34
       
35
       
 
       
                "remove_posts",

     

       
35
       
36
       
 
       
                "remove_comments",

     

       
36
       
37
       
 
       
                "ban_users",

     
···

       
38
       
39
       
 
       
                "manage_wiki",

     

       
39
       
40
       
 
       
                "manage_moderators",

     

       
40
       
41
       
 
       
                "manage_settings"

     

       
41
       
41
       
-
       
              ]

     

       
42
       
42
       
+
       
              ],

     

       
43
       
43
       
+
       
              "maxLength": 64

     

       
42
       
44
       
 
       
            }

     

       
43
       
45
       
 
       
          },

     

       
44
       
46
       
 
       
          "createdAt": {