···

       
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
       
 
       


     

···

       
4
       
4
       
 
       
  "defs": {

     

       
5
       
5
       
 
       
    "main": {

     

       
6
       
6
       
 
       
      "type": "procedure",

     

       
7
       
7
       
-
       
      "description": "Create a new community",

     

       
7
       
7
       
+
       
      "description": "Create a new community. Requires authentication.",

     

       
8
       
8
       
 
       
      "input": {

     

       
9
       
9
       
 
       
        "encoding": "application/json",

     

       
10
       
10
       
 
       
        "schema": {

     
···

       
66
       
66
       
 
       
            },

     

       
67
       
67
       
 
       
            "visibility": {

     

       
68
       
68
       
 
       
              "type": "string",

     

       
69
       
69
       
-
       
              "enum": ["public", "unlisted", "private"],

     

       
69
       
69
       
+
       
              "knownValues": ["public", "unlisted", "private"],

     

       
70
       
70
       
 
       
              "default": "public",

     

       
71
       
71
       
+
       
              "maxLength": 64,

     

       
71
       
72
       
 
       
              "description": "Community visibility level"

     

       
72
       
73
       
 
       
            },

     

       
73
       
74
       
 
       
            "allowExternalDiscovery": {

     

···

       
4
       
4
       
 
       
  "defs": {

     

       
5
       
5
       
 
       
    "main": {

     

       
6
       
6
       
 
       
      "type": "query",

     

       
7
       
7
       
-
       
      "description": "Get detailed information about a community",

     

       
7
       
7
       
+
       
      "description": "Get detailed information about a community. Authentication optional; viewer state will be included if authenticated.",

     

       
8
       
8
       
 
       
      "parameters": {

     

       
9
       
9
       
 
       
        "type": "params",

     

       
10
       
10
       
 
       
        "required": ["community"],

     
···

       
89
       
89
       
 
       
        },

     

       
90
       
90
       
 
       
        "member": {

     

       
91
       
91
       
 
       
          "type": "boolean",

     

       
92
       
92
       
-
       
          "description": "Whether the viewer has membership status"

     

       
93
       
93
       
-
       
        },

     

       
94
       
94
       
-
       
        "membershipUri": {

     

       
95
       
95
       
-
       
          "type": "string",

     

       
96
       
96
       
-
       
          "format": "at-uri",

     

       
97
       
97
       
-
       
          "description": "AT-URI of the membership record if member"

     

       
92
       
92
       
+
       
          "description": "Whether the viewer has membership status (AppView-computed)"

     

       
98
       
93
       
 
       
        },

     

       
99
       
94
       
 
       
        "reputation": {

     

       
100
       
95
       
 
       
          "type": "integer",

     

···

       
4
       
4
       
 
       
  "defs": {

     

       
5
       
5
       
 
       
    "main": {

     

       
6
       
6
       
 
       
      "type": "query",

     

       
7
       
7
       
-
       
      "description": "List communities with various sorting options",

     

       
7
       
7
       
+
       
      "description": "List communities with various sorting options. Authentication optional; viewer state will be included if authenticated.",

     

       
8
       
8
       
 
       
      "parameters": {

     

       
9
       
9
       
 
       
        "type": "params",

     

       
10
       
10
       
 
       
        "properties": {

     
···

       
20
       
20
       
 
       
          },

     

       
21
       
21
       
 
       
          "sort": {

     

       
22
       
22
       
 
       
            "type": "string",

     

       
23
       
23
       
-
       
            "enum": ["popular", "active", "new", "alphabetical"],

     

       
23
       
23
       
+
       
            "knownValues": ["popular", "active", "new", "alphabetical"],

     

       
24
       
24
       
 
       
            "default": "popular",

     

       
25
       
25
       
+
       
            "maxLength": 64,

     

       
25
       
26
       
 
       
            "description": "Sorting method"

     

       
26
       
27
       
 
       
          },

     

       
27
       
28
       
 
       
          "category": {

     

···

       
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": {

     

···

       
8
       
8
       
 
       
      "key": "literal:self",

     

       
9
       
9
       
 
       
      "record": {

     

       
10
       
10
       
 
       
        "type": "object",

     

       
11
       
11
       
-
       
        "required": ["handle", "name", "createdAt", "createdBy", "hostedBy", "visibility"],

     

       
11
       
11
       
+
       
        "required": ["handle", "name", "createdAt", "createdBy", "hostedBy", "visibility", "moderationType"],

     

       
12
       
12
       
 
       
        "properties": {

     

       
13
       
13
       
 
       
          "handle": {

     

       
14
       
14
       
 
       
            "type": "string",

     
···

       
63
       
63
       
 
       
          },

     

       
64
       
64
       
 
       
          "visibility": {

     

       
65
       
65
       
 
       
            "type": "string",

     

       
66
       
66
       
-
       
            "enum": ["public", "unlisted", "private"],

     

       
66
       
66
       
+
       
            "knownValues": ["public", "unlisted", "private"],

     

       
67
       
67
       
 
       
            "default": "public",

     

       
68
       
68
       
+
       
            "maxLength": 64,

     

       
68
       
69
       
 
       
            "description": "Community visibility level"

     

       
69
       
70
       
 
       
          },

     

       
70
       
71
       
 
       
          "federation": {

     
···

       
74
       
75
       
 
       
          },

     

       
75
       
76
       
 
       
          "moderationType": {

     

       
76
       
77
       
 
       
            "type": "string",

     

       
77
       
77
       
-
       
            "enum": ["moderator", "sortition"],

     

       
78
       
78
       
-
       
            "description": "Type of moderation system"

     

       
78
       
78
       
+
       
            "knownValues": ["moderator", "sortition"],

     

       
79
       
79
       
+
       
            "default": "moderator",

     

       
80
       
80
       
+
       
            "maxLength": 64,

     

       
81
       
81
       
+
       
            "description": "Type of moderation system (moderator=traditional moderator team, sortition=community tribunal)"

     

       
79
       
82
       
 
       
          },

     

       
80
       
83
       
 
       
          "contentWarnings": {

     

       
81
       
84
       
 
       
            "type": "array",

     

···

       
4
       
4
       
 
       
  "defs": {

     

       
5
       
5
       
 
       
    "main": {

     

       
6
       
6
       
 
       
      "type": "procedure",

     

       
7
       
7
       
-
       
      "description": "Subscribe to a community to see its posts in your feed",

     

       
7
       
7
       
+
       
      "description": "Subscribe to a community to see its posts in your feed. Requires authentication.",

     

       
8
       
8
       
 
       
      "input": {

     

       
9
       
9
       
 
       
        "encoding": "application/json",

     

       
10
       
10
       
 
       
        "schema": {

     

···

       
4
       
4
       
 
       
  "defs": {

     

       
5
       
5
       
 
       
    "main": {

     

       
6
       
6
       
 
       
      "type": "procedure",

     

       
7
       
7
       
-
       
      "description": "Unsubscribe from a community",

     

       
7
       
7
       
+
       
      "description": "Unsubscribe from a community. Requires authentication.",

     

       
8
       
8
       
 
       
      "input": {

     

       
9
       
9
       
 
       
        "encoding": "application/json",

     

       
10
       
10
       
 
       
        "schema": {

     

···

       
4
       
4
       
 
       
  "defs": {

     

       
5
       
5
       
 
       
    "main": {

     

       
6
       
6
       
 
       
      "type": "procedure",

     

       
7
       
7
       
-
       
      "description": "Update community profile",

     

       
7
       
7
       
+
       
      "description": "Update community profile. Requires authentication and moderator/admin permissions.",

     

       
8
       
8
       
 
       
      "input": {

     

       
9
       
9
       
 
       
        "encoding": "application/json",

     

       
10
       
10
       
 
       
        "schema": {

     
···

       
70
       
70
       
 
       
            },

     

       
71
       
71
       
 
       
            "visibility": {

     

       
72
       
72
       
 
       
              "type": "string",

     

       
73
       
73
       
-
       
              "enum": ["public", "unlisted", "private"],

     

       
73
       
73
       
+
       
              "knownValues": ["public", "unlisted", "private"],

     

       
74
       
74
       
+
       
              "maxLength": 64,

     

       
74
       
75
       
 
       
              "description": "Community visibility level"

     

       
75
       
76
       
 
       
            },

     

       
76
       
77
       
 
       
            "allowExternalDiscovery": {

     

···

       
1
       
1
       
-
       
{

     

       
2
       
2
       
-
       
  "$type": "social.coves.actor.membership",

     

       
3
       
3
       
-
       
  "community": "did:plc:examplecommunity123",

     

       
4
       
4
       
-
       
  "createdAt": "2024-01-15T10:30:00Z",

     

       
5
       
5
       
-
       
  "reputation": -50

     

       
6
       
6
       
-
       
}
     

···

       
1
       
1
       
-
       
{

     

       
2
       
2
       
-
       
  "$type": "social.coves.actor.membership",

     

       
3
       
3
       
-
       
  "community": "did:plc:examplecommunity123",

     

       
4
       
4
       
-
       
  "reputation": 150,

     

       
5
       
5
       
-
       
  "createdAt": "2024-01-15T10:30:00Z"

     

       
6
       
6
       
-
       
}