# PDS File Reorganization Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Reorganize pds.js into logical domain sections with box-style headers for improved readability.

**Architecture:** Reorder existing code into 12 logical domains without changing functionality. Add Unicode box-style section headers. Group related utilities that are currently scattered.

**Tech Stack:** JavaScript, JSDoc

---

## Box Header Format

All section headers use this format (80 chars wide):
```javascript
// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ SECTION NAME                                                                 ║
// ║ Brief description of what this section contains                              ║
// ╚══════════════════════════════════════════════════════════════════════════════╝
```

---

### Task 1: Types & Constants Section

**Files:**
- Modify: `src/pds.js` (lines 17-84, plus scattered constants)

**Step 1: Create the new section header and gather all types/constants**

Move these items to the top (after the file header comment):
- `CBOR_FALSE`, `CBOR_TRUE`, `CBOR_NULL`, `CBOR_TAG_CID` (from lines 19-24)
- `CODEC_DAG_CBOR`, `CODEC_RAW` (from lines 480-481)
- `TID_CHARS`, `clockId`, `lastTimestamp` (from lines 563-566)
- `P256_N`, `P256_N_DIV_2` (from lines 638-641)
- All typedefs: `Env`, `BlockRow`, `RecordRow`, `CommitRow`, `SeqEventRow`, `BlobRow`, `JwtPayload`

Add header:
```javascript
// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ TYPES & CONSTANTS                                                            ║
// ║ Environment bindings, SQL row types, protocol constants                      ║
// ╚══════════════════════════════════════════════════════════════════════════════╝
```

**Step 2: Run typecheck to verify no breakage**

Run: `npm run typecheck`
Expected: 0 errors

**Step 3: Commit**

```bash
git add src/pds.js
git commit -m "refactor: consolidate types and constants section"
```

---

### Task 2: Utilities Section

**Files:**
- Modify: `src/pds.js`

**Step 1: Create utilities section after types/constants**

Move these functions together:
- `errorResponse()` (from line 92)
- `bytesToHex()` (from line 990)
- `hexToBytes()` (from line 1001)
- `bytesToBigInt()` (from line 647)
- `bigIntToBytes()` (from line 660)
- `base32Encode()` (from line 538)
- `base32Decode()` (from line 1237)
- `base64UrlEncode()` (from line 745)
- `base64UrlDecode()` (from line 759)
- `varint()` (from line 1211)

Add header:
```javascript
// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ UTILITIES                                                                    ║
// ║ Error responses, byte conversion, base encoding                              ║
// ╚══════════════════════════════════════════════════════════════════════════════╝
```

**Step 2: Run typecheck**

Run: `npm run typecheck`
Expected: 0 errors

**Step 3: Commit**

```bash
git add src/pds.js
git commit -m "refactor: consolidate utilities section"
```

---

### Task 3: CBOR Encoding Section

**Files:**
- Modify: `src/pds.js`

**Step 1: Create CBOR section**

Keep together (already grouped, just add new header):
- `encodeHead()`
- `cborEncode()`
- `cborEncodeDagCbor()`
- `cborDecode()`

Replace `// === CBOR ENCODING ===` with:
```javascript
// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ CBOR ENCODING                                                                ║
// ║ RFC 8949 CBOR and DAG-CBOR for content-addressed data                        ║
// ╚══════════════════════════════════════════════════════════════════════════════╝
```

**Step 2: Run typecheck**

Run: `npm run typecheck`
Expected: 0 errors

**Step 3: Commit**

```bash
git add src/pds.js
git commit -m "refactor: add CBOR encoding section header"
```

---

### Task 4: Content Identifiers Section

**Files:**
- Modify: `src/pds.js`

**Step 1: Create CID/TID section**

Group together:
- `class CID` (from line 238)
- `createCidWithCodec()` (from line 489)
- `createCid()` (from line 510)
- `createBlobCid()` (from line 519)
- `cidToString()` (from line 528)
- `cidToBytes()` (from line 1226)
- `createTid()` (from line 572)

Add header:
```javascript
// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ CONTENT IDENTIFIERS                                                          ║
// ║ CIDs (content hashes) and TIDs (timestamp IDs)                               ║
// ╚══════════════════════════════════════════════════════════════════════════════╝
```

**Step 2: Run typecheck**

Run: `npm run typecheck`
Expected: 0 errors

**Step 3: Commit**

```bash
git add src/pds.js
git commit -m "refactor: consolidate content identifiers section"
```

---

### Task 5: Cryptography Section

**Files:**
- Modify: `src/pds.js`

**Step 1: Create cryptography section**

Group together:
- `sha256()` (from line 1016)
- `importPrivateKey()` (from line 606)
- `generateKeyPair()` (from line 705)
- `compressPublicKey()` (from line 728)
- `sign()` (from line 675)

Add header:
```javascript
// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ CRYPTOGRAPHY                                                                 ║
// ║ P-256 signing with low-S normalization, key management                       ║
// ╚══════════════════════════════════════════════════════════════════════════════╝
```

**Step 2: Run typecheck**

Run: `npm run typecheck`
Expected: 0 errors

**Step 3: Commit**

```bash
git add src/pds.js
git commit -m "refactor: create cryptography section"
```

---

### Task 6: Authentication Section

**Files:**
- Modify: `src/pds.js`

**Step 1: Create authentication section**

Group together:
- `hmacSign()` (from line 777)
- `createAccessJwt()` (from line 800)
- `createRefreshJwt()` (from line 829)
- `verifyJwt()` (from line 876)
- `verifyAccessJwt()` (from line 919)
- `verifyRefreshJwt()` (from line 931)
- `createServiceJwt()` (from line 952)

Add header:
```javascript
// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ AUTHENTICATION                                                               ║
// ║ JWT creation/verification for sessions and service auth                      ║
// ╚══════════════════════════════════════════════════════════════════════════════╝
```

**Step 2: Run typecheck**

Run: `npm run typecheck`
Expected: 0 errors

**Step 3: Commit**

```bash
git add src/pds.js
git commit -m "refactor: create authentication section"
```

---

### Task 7: Merkle Search Tree Section

**Files:**
- Modify: `src/pds.js`

**Step 1: Update MST section header**

Keep together (already grouped):
- `keyDepthCache`
- `getKeyDepth()`
- `commonPrefixLen()`
- `class MST`

Replace `// === MERKLE SEARCH TREE ===` with:
```javascript
// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ MERKLE SEARCH TREE                                                           ║
// ║ MST for ATProto repository structure                                         ║
// ╚══════════════════════════════════════════════════════════════════════════════╝
```

**Step 2: Run typecheck**

Run: `npm run typecheck`
Expected: 0 errors

**Step 3: Commit**

```bash
git add src/pds.js
git commit -m "refactor: update MST section header"
```

---

### Task 8: CAR Files Section

**Files:**
- Modify: `src/pds.js`

**Step 1: Update CAR section**

Keep only:
- `buildCarFile()`

(Note: `varint()`, `cidToBytes()`, `base32Decode()` moved to earlier sections)

Replace `// === CAR FILE BUILDER ===` with:
```javascript
// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ CAR FILES                                                                    ║
// ║ Content Addressable aRchive format for repo sync                             ║
// ╚══════════════════════════════════════════════════════════════════════════════╝
```

**Step 2: Run typecheck**

Run: `npm run typecheck`
Expected: 0 errors

**Step 3: Commit**

```bash
git add src/pds.js
git commit -m "refactor: update CAR files section"
```

---

### Task 9: Blob Handling Section

**Files:**
- Modify: `src/pds.js`

**Step 1: Create blob handling section**

Group together:
- `sniffMimeType()` (from line 105)
- `findBlobRefs()` (from line 181)
- `CRAWL_NOTIFY_THRESHOLD`, `lastCrawlNotify` (from lines 207-208)
- `notifyCrawlers()` (from line 214)

Add header:
```javascript
// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ BLOB HANDLING                                                                ║
// ║ MIME detection, blob reference scanning, crawler notification                ║
// ╚══════════════════════════════════════════════════════════════════════════════╝
```

**Step 2: Run typecheck**

Run: `npm run typecheck`
Expected: 0 errors

**Step 3: Commit**

```bash
git add src/pds.js
git commit -m "refactor: create blob handling section"
```

---

### Task 10: Routing Section

**Files:**
- Modify: `src/pds.js`

**Step 1: Add routing section header**

Before `RouteHandler` callback typedef, add:
```javascript
// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ ROUTING                                                                      ║
// ║ XRPC endpoint definitions                                                    ║
// ╚══════════════════════════════════════════════════════════════════════════════╝
```

This section contains:
- `RouteHandler` (callback typedef)
- `Route` (typedef)
- `pdsRoutes`

**Step 2: Run typecheck**

Run: `npm run typecheck`
Expected: 0 errors

**Step 3: Commit**

```bash
git add src/pds.js
git commit -m "refactor: add routing section header"
```

---

### Task 11: Personal Data Server Section

**Files:**
- Modify: `src/pds.js`

**Step 1: Add PDS class section header**

Before `class PersonalDataServer`, add:
```javascript
// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ PERSONAL DATA SERVER                                                         ║
// ║ Durable Object class implementing ATProto PDS                                ║
// ╚══════════════════════════════════════════════════════════════════════════════╝
```

**Step 2: Run typecheck**

Run: `npm run typecheck`
Expected: 0 errors

**Step 3: Commit**

```bash
git add src/pds.js
git commit -m "refactor: add PDS class section header"
```

---

### Task 12: Workers Entry Point Section

**Files:**
- Modify: `src/pds.js`

**Step 1: Add workers entry point section header**

Before `corsHeaders`, add:
```javascript
// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ WORKERS ENTRY POINT                                                          ║
// ║ Request handling, CORS, auth middleware                                      ║
// ╚══════════════════════════════════════════════════════════════════════════════╝
```

This section contains:
- `corsHeaders`
- `addCorsHeaders()`
- `getSubdomain()`
- `requireAuth()`
- `handleAuthenticatedBlobUpload()`
- `handleAuthenticatedRepoWrite()`
- `handleRequest()`
- `default export`

**Step 2: Run typecheck**

Run: `npm run typecheck`
Expected: 0 errors

**Step 3: Commit**

```bash
git add src/pds.js
git commit -m "refactor: add workers entry point section header"
```

---

### Task 13: Final Verification

**Step 1: Run full typecheck**

Run: `npm run typecheck`
Expected: 0 errors

**Step 2: Run tests**

Run: `npm test`
Expected: All tests pass

**Step 3: Run e2e tests if available**

Run: `npm run test:e2e`
Expected: All tests pass

**Step 4: Final commit if any cleanup needed**

```bash
git add src/pds.js
git commit -m "refactor: complete pds.js reorganization with box headers"
```

---

## Section Order Summary

Final file structure (top to bottom):
1. File header comment
2. TYPES & CONSTANTS
3. UTILITIES
4. CBOR ENCODING
5. CONTENT IDENTIFIERS
6. CRYPTOGRAPHY
7. AUTHENTICATION
8. MERKLE SEARCH TREE
9. CAR FILES
10. BLOB HANDLING
11. ROUTING
12. PERSONAL DATA SERVER
13. WORKERS ENTRY POINT