feat(lexicon): make moderator roles and permissions extensible

A community based topic aggregation platform built on atproto

BREAKING: This is a pre-alpha schema fix. Must be applied before any
moderator records are created.

Changes to social.coves.community.moderator:
- Change role from enum to knownValues (enables future role types)
- Change permissions from enum to knownValues (enables new permissions)
- Add maxLength: 64 to both fields per atProto style guide

Future extensibility examples:
- Roles: "owner", "trainee", "emeritus"
- Permissions: "manage_bots", "manage_flairs", "manage_automoderator"

Documented in PRD_GOVERNANCE.md:
- Technical decision rationale
- atProto style guide reference
- Future beta phase extensibility plan
- Security considerations

This enables Beta Phase 2 (Moderator Tiers & Permissions) without
requiring V2 schema migration or breaking existing records.

Per atProto style guide (bluesky-social/atproto#4245): enum sets
cannot be extended without breaking schema evolution rules.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

bretton.dev 4 months ago 578a3023 214e2008

+30 -3

2 changed files

expand all

unified split

docs

PRD_GOVERNANCE.md

internal

atproto

lexicon

social

coves

community

moderator.json

+25

docs/PRD_GOVERNANCE.md

··· 390 390 391 391 ## Technical Decisions Log 392 392 393 + ### 2025-10-18: Moderator Lexicon Extensibility 394 + **Decision:** Use `knownValues` instead of `enum` for moderator roles and permissions in `social.coves.community.moderator` record schema 395 + 396 + **Rationale:** 397 + - Moderator records are immutable once published (atProto record semantics) 398 + - Closed `enum` values cannot be extended without breaking schema evolution rules 399 + - Using `knownValues` allows adding new roles/permissions in Beta Phase 2 without requiring V2 schema migration 400 + - Zero cost to fix during alpha planning; expensive to migrate once records exist in production 401 + 402 + **Changes Made:** 403 + - `role` field: Changed from `enum: ["moderator", "admin"]` to `knownValues: ["moderator", "admin"]` with `maxLength: 64` 404 + - `permissions` array items: Changed from closed enum to `knownValues` with `maxLength: 64` 405 + 406 + **Future Extensibility Examples:** 407 + - **New roles**: "owner" (full transfer rights), "trainee" (limited trial moderator), "emeritus" (honorary former moderator) 408 + - **New permissions**: "manage_bots", "manage_flairs", "manage_automoderator", "manage_federation", "pin_posts" 409 + - Can add these values during Phase 2 (Moderator Tiers & Permissions) without breaking existing moderator records 410 + 411 + **atProto Style Guide Reference:** 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 + 414 + **Implementation Status:** ✅ Fixed in lexicon before alpha launch 415 + 416 + --- 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