start researching quotas based on layer size per DID

docs/QUOTAS.md

···
 # ATCR Quota System
 
-This document describes ATCR's storage quota implementation, inspired by Harbor's proven approach to per-project blob tracking with deduplication.
+This document describes ATCR's storage quota implementation using ATProto records for per-user layer tracking.
 
 ## Table of Contents
 
 - [Overview](#overview)
-- [Harbor's Approach (Reference Implementation)](#harbors-approach-reference-implementation)
-- [Storage Options](#storage-options)
-- [Quota Data Model](#quota-data-model)
-- [Push Flow (Detailed)](#push-flow-detailed)
+- [Quota Model](#quota-model)
+- [Layer Record Schema](#layer-record-schema)
+- [Quota Calculation](#quota-calculation)
+- [Push Flow](#push-flow)
 - [Delete Flow](#delete-flow)
 - [Garbage Collection](#garbage-collection)
-- [Quota Reconciliation](#quota-reconciliation)
 - [Configuration](#configuration)
-- [Trade-offs & Design Decisions](#trade-offs--design-decisions)
 - [Future Enhancements](#future-enhancements)
 
 ## Overview
 
 ATCR implements per-user storage quotas to:
 1. **Limit storage consumption** on shared hold services
-2. **Track actual S3 costs** (what new data was added)
-3. **Benefit from deduplication** (users only pay once per layer)
-4. **Provide transparency** (show users their storage usage)
+2. **Provide transparency** (show users their storage usage)
+3. **Enable fair billing** (users pay for what they use)
 
-**Key principle:** Users pay for layers they've uploaded, but only ONCE per layer regardless of how many images reference it.
+**Key principle:** Users pay for layers they reference, deduplicated per-user. If you push the same layer in multiple images, you only pay once.
 
 ### Example Scenario
 
 ```
 Alice pushes myapp:v1 (layers A, B, C - each 100MB)
-→ Alice's quota: +300MB (all new layers)
+→ Creates 3 layer records in hold's PDS
+→ Alice's quota: 300MB (3 unique layers)
 
 Alice pushes myapp:v2 (layers A, B, D)
-→ Layers A, B already claimed by Alice
-→ Layer D is new (100MB)
-→ Alice's quota: +100MB (only D is new)
-→ Total: 400MB
+→ Creates 3 more layer records (A, B again, plus D)
+→ Alice's quota: 400MB (4 unique layers: A, B, C, D)
+→ Layers A, B appear twice in records but deduplicated in quota calc
 
 Bob pushes his-app:latest (layers A, E)
-→ Layer A already exists in S3 (uploaded by Alice)
-→ Bob claims it for first time → +100MB to Bob's quota
-→ Layer E is new → +100MB to Bob's quota
-→ Bob's quota: 200MB
+→ Creates 2 layer records for Bob
+→ Bob's quota: 200MB (2 unique layers: A, E)
+→ Layer A shared with Alice in S3, but Bob pays for his own usage
 
-Physical S3 storage: 500MB (A, B, C, D, E)
-Claimed storage: 600MB (Alice: 400MB, Bob: 200MB)
-Deduplication savings: 100MB (layer A shared)
+Physical S3 storage: 500MB (A, B, C, D, E - deduplicated globally)
+Alice's quota: 400MB
+Bob's quota: 200MB
 ```
 
-## Harbor's Approach (Reference Implementation)
+## Quota Model
 
-Harbor is built on distribution/distribution (same as ATCR) and implements quotas as middleware. Their approach:
+### Everyone Pays for What They Upload
 
-### Key Insights from Harbor
+Each user is charged for all unique layers they reference, regardless of whether those layers exist in S3 from other users' uploads.
 
-1. **"Shared blobs are only computed once per project"**
-   - Each project tracks which blobs it has uploaded
-   - Same blob used in multiple images counts only once per project
-   - Different projects claiming the same blob each pay for it
+**Why this model?**
+- **Simple mental model**: "I pushed 500MB of layers, I use 500MB of quota"
+- **Predictable**: Your quota doesn't change based on others' actions
+- **Clean deletion**: Delete manifest → layer records removed → quota freed
+- **No cross-user dependencies**: Users are isolated
 
-2. **Quota checked when manifest is pushed**
-   - Blobs upload first (presigned URLs, can't intercept)
-   - Manifest pushed last → quota check happens here
-   - Can reject manifest if quota exceeded (orphaned blobs cleaned by GC)
+**Trade-off:**
+- Total claimed storage can exceed physical S3 storage
+- This is acceptable - deduplication is an operational benefit for ATCR, not a billing feature
 
-3. **Middleware-based implementation**
-   - distribution/distribution has NO built-in quota support
-   - Harbor added it as request preprocessing middleware
-   - Uses database (PostgreSQL) or Redis for quota storage
+### ATProto-Native Storage
 
-4. **Per-project ownership model**
-   - Blobs are physically deduplicated globally
-   - Quota accounting is logical (per-project claims)
-   - Total claimed storage can exceed physical storage
+Layer tracking uses ATProto records stored in the hold's embedded PDS:
+- **Collection**: `io.atcr.hold.layer`
+- **Repository**: Hold's DID (e.g., `did:web:hold01.atcr.io`)
+- **Records**: One per manifest-layer relationship (TID-based keys)
 
-### References
+This approach:
+- Keeps quota data in ATProto (no separate database)
+- Enables standard ATProto sync/query mechanisms
+- Provides full audit trail of layer usage
 
-- Harbor Quota Documentation: https://goharbor.io/docs/1.10/administration/configure-project-quotas/
-- Harbor Source: https://github.com/goharbor/harbor (see `src/controller/quota`)
+## Layer Record Schema
 
-## Storage Options
+### LayerRecord
 
-The hold service needs to store quota data somewhere. Two options:
-
-### Option 1: S3-Based Storage (Recommended for BYOS)
-
-Store quota metadata alongside blobs in the same S3 bucket:
+```go
+// pkg/atproto/lexicon.go
 
-```
-Bucket structure:
-/docker/registry/v2/blobs/sha256/ab/abc123.../data   ← actual blobs
-/atcr/quota/did:plc:alice.json                        ← quota tracking
-/atcr/quota/did:plc:bob.json
+type LayerRecord struct {
+    Type      string `json:"$type"`     // "io.atcr.hold.layer"
+    Digest    string `json:"digest"`    // Layer digest (sha256:abc123...)
+    Size      int64  `json:"size"`      // Size in bytes
+    MediaType string `json:"mediaType"` // e.g., "application/vnd.oci.image.layer.v1.tar+gzip"
+    Manifest  string `json:"manifest"`  // at://did:plc:alice/io.atcr.manifest/abc123
+    UserDID   string `json:"userDid"`   // User's DID for quota grouping
+    CreatedAt string `json:"createdAt"` // ISO 8601 timestamp
+}
 ```
 
-**Pros:**
-- ✅ No separate database needed
-- ✅ Single S3 bucket (better UX - no second bucket to configure)
-- ✅ Quota data lives with the blobs
-- ✅ Hold service stays relatively stateless
-- ✅ Works with any S3-compatible service (Storj, Minio, Upcloud, Fly.io)
-
-**Cons:**
-- ❌ Slower than local database (network round-trip)
-- ❌ Eventual consistency issues
-- ❌ Race conditions on concurrent updates
-- ❌ Extra S3 API costs (GET/PUT per upload)
+### Record Key
 
-**Performance:**
-- Each blob upload: 1 HEAD (blob exists?) + 1 GET (quota) + 1 PUT (update quota)
-- Typical latency: 100-200ms total overhead
-- For high-throughput registries, consider SQLite
+Records use TID (timestamp-based ID) as the rkey. This means:
+- Multiple records can exist for the same layer (from different manifests)
+- Deduplication happens at query time, not storage time
+- Simple append-only writes on manifest push
 
-### Option 2: SQLite Database (Recommended for Shared Holds)
+### Example Records
 
-Local database in hold service:
-
-```bash
-/var/lib/atcr/hold-quota.db
 ```
-
-**Pros:**
-- ✅ Fast local queries (no network latency)
-- ✅ ACID transactions (no race conditions)
-- ✅ Efficient for high-throughput registries
-- ✅ Can use foreign keys and joins
+Manifest A (layers X, Y, Z) → creates 3 records
+Manifest B (layers X, W)    → creates 2 records
 
-**Cons:**
-- ❌ Makes hold service stateful (persistent volume needed)
-- ❌ Not ideal for ephemeral BYOS deployments
-- ❌ Backup/restore complexity
-- ❌ Multi-instance scaling requires shared database
-
-**Schema:**
-```sql
-CREATE TABLE user_quotas (
-    did TEXT PRIMARY KEY,
-    quota_limit INTEGER NOT NULL DEFAULT 10737418240,  -- 10GB
-    quota_used INTEGER NOT NULL DEFAULT 0,
-    updated_at TIMESTAMP
-);
-
-CREATE TABLE claimed_layers (
-    did TEXT NOT NULL,
-    digest TEXT NOT NULL,
-    size INTEGER NOT NULL,
-    claimed_at TIMESTAMP,
-    PRIMARY KEY(did, digest)
-);
+io.atcr.hold.layer collection:
+┌──────────────┬────────┬──────┬───────────────────────────────────┬─────────────────┐
+│ rkey (TID)   │ digest │ size │ manifest                          │ userDid         │
+├──────────────┼────────┼──────┼───────────────────────────────────┼─────────────────┤
+│ 3jui7...001  │ X      │ 100  │ at://did:plc:alice/.../manifestA  │ did:plc:alice   │
+│ 3jui7...002  │ Y      │ 200  │ at://did:plc:alice/.../manifestA  │ did:plc:alice   │
+│ 3jui7...003  │ Z      │ 150  │ at://did:plc:alice/.../manifestA  │ did:plc:alice   │
+│ 3jui7...004  │ X      │ 100  │ at://did:plc:alice/.../manifestB  │ did:plc:alice   │  ← duplicate digest
+│ 3jui7...005  │ W      │ 300  │ at://did:plc:alice/.../manifestB  │ did:plc:alice   │
+└──────────────┴────────┴──────┴───────────────────────────────────┴─────────────────┘
 ```
 
-### Recommendation
+## Quota Calculation
 
-- **BYOS (user-owned holds):** S3-based (keeps hold service ephemeral)
-- **Shared holds (multi-user):** SQLite (better performance and consistency)
-- **High-traffic production:** SQLite or PostgreSQL (Harbor uses this)
+### Query: User's Unique Storage
 
-## Quota Data Model
-
-### Quota File Format (S3-based)
-
-```json
-{
-  "did": "did:plc:alice123",
-  "limit": 10737418240,
-  "used": 5368709120,
-  "claimed_layers": {
-    "sha256:abc123...": 104857600,
-    "sha256:def456...": 52428800,
-    "sha256:789ghi...": 209715200
-  },
-  "last_updated": "2025-10-09T12:34:56Z",
-  "version": 1
-}
+```sql
+-- Calculate quota by deduplicating layers
+SELECT SUM(size) FROM (
+    SELECT DISTINCT digest, size
+    FROM io.atcr.hold.layer
+    WHERE userDid = ?
+)
 ```
 
-**Fields:**
-- `did`: User's ATProto DID
-- `limit`: Maximum storage in bytes (default: 10GB)
-- `used`: Current storage usage in bytes (sum of claimed_layers)
-- `claimed_layers`: Map of digest → size for all layers user has uploaded
-- `last_updated`: Timestamp of last quota update
-- `version`: Schema version for future migrations
-
-### Why Track Individual Layers?
-
-**Q: Can't we just track a counter?**
-
-**A: We need layer tracking for:**
-
-1. **Deduplication detection**
-   - Check if user already claimed a layer → free upload
-   - Example: Updating an image reuses most layers
-
-2. **Accurate deletes**
-   - When manifest deleted, only decrement unclaimed layers
-   - User may have 5 images sharing layer A - deleting 1 image doesn't free layer A
-
-3. **Quota reconciliation**
-   - Verify quota matches reality by listing user's manifests
-   - Recalculate from layers in manifests vs claimed_layers map
+Using the example above:
+- Layer X appears twice but counted once: 100
+- Layers Y, Z, W counted once each: 200 + 150 + 300
+- **Total: 750 bytes**
 
-4. **Auditing**
-   - "Show me what I'm storing"
-   - Users can see which layers consume their quota
-
-## Push Flow (Detailed)
-
-### Step-by-Step: User Pushes Image
-
-```
-┌──────────┐                ┌──────────┐                ┌──────────┐
-│  Client  │                │   Hold   │                │    S3    │
-│ (Docker) │                │ Service  │                │  Bucket  │
-└──────────┘                └──────────┘                └──────────┘
-     │                            │                            │
-     │ 1. PUT /v2/.../blobs/      │                            │
-     │    upload?digest=sha256:abc│                            │
-     ├───────────────────────────>│                            │
-     │                            │                            │
-     │                            │ 2. Check if blob exists    │
-     │                            │    (Stat/HEAD request)     │
-     │                            ├───────────────────────────>│
-     │                            │<───────────────────────────┤
-     │                            │    200 OK (exists) or      │
-     │                            │    404 Not Found           │
-     │                            │                            │
-     │                            │ 3. Read user quota         │
-     │                            │    GET /atcr/quota/{did}   │
-     │                            ├───────────────────────────>│
-     │                            │<───────────────────────────┤
-     │                            │    quota.json              │
-     │                            │                            │
-     │                            │ 4. Calculate quota impact  │
-     │                            │    - If digest in          │
-     │                            │      claimed_layers: 0     │
-     │                            │    - Else: size            │
-     │                            │                            │
-     │                            │ 5. Check quota limit       │
-     │                            │    used + impact <= limit? │
-     │                            │                            │
-     │                            │ 6. Update quota            │
-     │                            │    PUT /atcr/quota/{did}   │
-     │                            ├───────────────────────────>│
-     │                            │<───────────────────────────┤
-     │                            │    200 OK                  │
-     │                            │                            │
-     │ 7. Presigned URL           │                            │
-     │<───────────────────────────┤                            │
-     │ {url: "https://s3..."}     │                            │
-     │                            │                            │
-     │ 8. Upload blob to S3       │                            │
-     ├────────────────────────────┼───────────────────────────>│
-     │                            │                            │
-     │ 9. 200 OK                  │                            │
-     │<───────────────────────────┼────────────────────────────┤
-     │                            │                            │
-```
-
-### Implementation (Pseudocode)
+### Implementation
 
 ```go
-// cmd/hold/main.go - HandlePutPresignedURL
+// pkg/hold/quota/quota.go
 
-func (s *HoldService) HandlePutPresignedURL(w http.ResponseWriter, r *http.Request) {
-    var req PutPresignedURLRequest
-    json.NewDecoder(r.Body).Decode(&req)
+type QuotaManager struct {
+    pds *pds.Server  // Hold's embedded PDS
+}
 
-    // Step 1: Check if blob already exists in S3
-    blobPath := fmt.Sprintf("/docker/registry/v2/blobs/%s/%s/%s/data",
-        algorithm, digest[:2], digest)
-
-    _, err := s.driver.Stat(ctx, blobPath)
-    blobExists := (err == nil)
-
-    // Step 2: Read quota from S3 (or SQLite)
-    quota, err := s.quotaManager.GetQuota(req.DID)
+// GetUsage calculates a user's current quota usage
+func (q *QuotaManager) GetUsage(ctx context.Context, userDID string) (int64, error) {
+    // List all layer records for this user
+    records, err := q.pds.ListRecords(ctx, LayerCollection, userDID)
     if err != nil {
-        // First upload - create quota with defaults
-        quota = &Quota{
-            DID:           req.DID,
-            Limit:         s.config.QuotaDefaultLimit,
-            Used:          0,
-            ClaimedLayers: make(map[string]int64),
-        }
+        return 0, err
     }
 
-    // Step 3: Calculate quota impact
-    quotaImpact := req.Size  // Default: assume new layer
-
-    if _, alreadyClaimed := quota.ClaimedLayers[req.Digest]; alreadyClaimed {
-        // User already uploaded this layer before
-        quotaImpact = 0
-        log.Printf("Layer %s already claimed by %s, no quota impact",
-            req.Digest, req.DID)
-    } else if blobExists {
-        // Blob exists in S3 (uploaded by another user)
-        // But this user is claiming it for first time
-        // Still counts against their quota
-        log.Printf("Layer %s exists globally but new to %s, quota impact: %d",
-            req.Digest, req.DID, quotaImpact)
-    } else {
-        // Brand new blob - will be uploaded to S3
-        log.Printf("New layer %s for %s, quota impact: %d",
-            req.Digest, req.DID, quotaImpact)
+    // Deduplicate by digest
+    uniqueLayers := make(map[string]int64) // digest -> size
+    for _, record := range records {
+        var layer LayerRecord
+        if err := json.Unmarshal(record.Value, &layer); err != nil {
+            continue
+        }
+        if layer.UserDID == userDID {
+            uniqueLayers[layer.Digest] = layer.Size
+        }
     }
 
-    // Step 4: Check quota limit
-    if quota.Used + quotaImpact > quota.Limit {
-        http.Error(w, fmt.Sprintf(
-            "quota exceeded: used=%d, impact=%d, limit=%d",
-            quota.Used, quotaImpact, quota.Limit,
-        ), http.StatusPaymentRequired)  // 402
-        return
-    }
-
-    // Step 5: Update quota (optimistic - before upload completes)
-    quota.Used += quotaImpact
-    if quotaImpact > 0 {
-        quota.ClaimedLayers[req.Digest] = req.Size
+    // Sum unique layer sizes
+    var total int64
+    for _, size := range uniqueLayers {
+        total += size
     }
-    quota.LastUpdated = time.Now()
 
-    if err := s.quotaManager.SaveQuota(quota); err != nil {
-        http.Error(w, "failed to update quota", http.StatusInternalServerError)
-        return
-    }
+    return total, nil
+}
 
-    // Step 6: Generate presigned URL
-    presignedURL, err := s.getUploadURL(ctx, req.Digest, req.Size, req.DID)
+// CheckQuota returns true if user has space for additional bytes
+func (q *QuotaManager) CheckQuota(ctx context.Context, userDID string, additional int64, limit int64) (bool, int64, error) {
+    current, err := q.GetUsage(ctx, userDID)
     if err != nil {
-        // Rollback quota update on error
-        quota.Used -= quotaImpact
-        delete(quota.ClaimedLayers, req.Digest)
-        s.quotaManager.SaveQuota(quota)
-
-        http.Error(w, "failed to generate presigned URL", http.StatusInternalServerError)
-        return
-    }
-
-    // Step 7: Return presigned URL + quota info
-    resp := PutPresignedURLResponse{
-        URL:       presignedURL,
-        ExpiresAt: time.Now().Add(15 * time.Minute),
-        QuotaInfo: QuotaInfo{
-            Used:           quota.Used,
-            Limit:          quota.Limit,
-            Available:      quota.Limit - quota.Used,
-            Impact:         quotaImpact,
-            AlreadyClaimed: quotaImpact == 0,
-        },
+        return false, 0, err
     }
 
-    w.Header().Set("Content-Type", "application/json")
-    json.NewEncoder(w).Encode(resp)
+    return current+additional <= limit, current, nil
 }
 ```
 
-### Race Condition Handling
-
-**Problem:** Two concurrent uploads of the same blob
+### Quota Response
 
-```
-Time    User A                          User B
-0ms     Upload layer X (100MB)
-10ms                                    Upload layer X (100MB)
-20ms    Check exists: NO                Check exists: NO
-30ms    Quota impact: 100MB             Quota impact: 100MB
-40ms    Update quota A: +100MB          Update quota B: +100MB
-50ms    Generate presigned URL          Generate presigned URL
-100ms   Upload to S3 completes          Upload to S3 (overwrites A's)
+```go
+type QuotaInfo struct {
+    Used      int64 `json:"used"`      // Current usage (deduplicated)
+    Limit     int64 `json:"limit"`     // User's quota limit
+    Available int64 `json:"available"` // Remaining space
+}
 ```
 
-**Result:** Both users charged 100MB, but only 100MB stored in S3.
+## Push Flow
 
-**Mitigation strategies:**
-
-1. **Accept eventual consistency** (recommended for S3-based)
-   - Run periodic reconciliation to fix discrepancies
-   - Small inconsistency window (minutes) is acceptable
-   - Reconciliation uses PDS as source of truth
-
-2. **Optimistic locking** (S3 ETags)
-   ```go
-   // Use S3 ETags for conditional writes
-   oldETag := getQuotaFileETag(did)
-   err := putQuotaFileWithCondition(quota, oldETag)
-   if err == PreconditionFailed {
-       // Retry with fresh read
-   }
-   ```
-
-3. **Database transactions** (SQLite-based)
-   ```sql
-   BEGIN TRANSACTION;
-   SELECT * FROM user_quotas WHERE did = ? FOR UPDATE;
-   UPDATE user_quotas SET used = used + ? WHERE did = ?;
-   COMMIT;
-   ```
-
-## Delete Flow
-
-### Manifest Deletion via AppView UI
-
-When a user deletes a manifest through the AppView web interface:
+### Step-by-Step: User Pushes Image
 
 ```
 ┌──────────┐          ┌──────────┐          ┌──────────┐          ┌──────────┐
-│   User   │          │ AppView  │          │   Hold   │          │    PDS   │
-│    UI    │          │ Database │          │ Service  │          │          │
+│  Client  │          │ AppView  │          │   Hold   │          │ User PDS │
+│ (Docker) │          │          │          │ Service  │          │          │
 └──────────┘          └──────────┘          └──────────┘          └──────────┘
      │                      │                      │                      │
-     │ DELETE manifest      │                      │                      │
+     │ 1. Upload blobs      │                      │                      │
      ├─────────────────────>│                      │                      │
+     │                      │ 2. Route to hold     │                      │
+     │                      ├─────────────────────>│                      │
+     │                      │                      │ 3. Store in S3       │
      │                      │                      │                      │
-     │                      │ 1. Get manifest      │                      │
-     │                      │    and layers        │                      │
+     │ 4. PUT manifest      │                      │                      │
+     ├─────────────────────>│                      │                      │
      │                      │                      │                      │
-     │                      │ 2. Check which       │                      │
-     │                      │    layers still      │                      │
-     │                      │    referenced by     │                      │
-     │                      │    user's other      │                      │
-     │                      │    manifests         │                      │
+     │                      │ 5. Calculate quota   │                      │
+     │                      │    impact for new    │                      │
+     │                      │    layers            │                      │
+     │                      │                      │                      │
+     │                      │ 6. Check quota limit │                      │
+     │                      ├─────────────────────>│                      │
+     │                      │<─────────────────────┤                      │
      │                      │                      │                      │
-     │                      │ 3. DELETE manifest   │                      │
-     │                      │    from PDS          │                      │
+     │                      │ 7. Store manifest    │                      │
      │                      ├──────────────────────┼─────────────────────>│
      │                      │                      │                      │
-     │                      │ 4. POST /quota/decrement                    │
+     │                      │ 8. Create layer      │                      │
+     │                      │    records           │                      │
      │                      ├─────────────────────>│                      │
-     │                      │ {layers: [...]}      │                      │
-     │                      │                      │                      │
-     │                      │                      │ 5. Update quota      │
-     │                      │                      │    Remove unclaimed  │
-     │                      │                      │    layers            │
-     │                      │                      │                      │
-     │                      │ 6. 200 OK            │                      │
-     │                      │<─────────────────────┤                      │
-     │                      │                      │                      │
-     │                      │ 7. Delete from DB    │                      │
+     │                      │                      │ 9. Write to          │
+     │                      │                      │    hold's PDS        │
      │                      │                      │                      │
-     │ 8. Success           │                      │                      │
+     │ 10. 201 Created      │                      │                      │
      │<─────────────────────┤                      │                      │
-     │                      │                      │                      │
 ```
 
-### AppView Implementation
+### Implementation
 
 ```go
-// pkg/appview/handlers/manifest.go
+// pkg/appview/storage/routing_repository.go
 
-func (h *ManifestHandler) DeleteManifest(w http.ResponseWriter, r *http.Request) {
-    did := r.Context().Value("auth.did").(string)
-    repository := chi.URLParam(r, "repository")
-    digest := chi.URLParam(r, "digest")
+func (r *RoutingRepository) PutManifest(ctx context.Context, manifest distribution.Manifest) error {
+    // Parse manifest to get layers
+    layers := extractLayers(manifest)
 
-    // Step 1: Get manifest and its layers from database
-    manifest, err := db.GetManifest(h.db, digest)
+    // Get user's current unique layers from hold
+    existingLayers, err := r.holdClient.GetUserLayers(ctx, r.userDID)
     if err != nil {
-        http.Error(w, "manifest not found", 404)
-        return
+        return err
     }
+    existingSet := makeDigestSet(existingLayers)
 
-    layers, err := db.GetLayersForManifest(h.db, manifest.ID)
-    if err != nil {
-        http.Error(w, "failed to get layers", 500)
-        return
-    }
-
-    // Step 2: For each layer, check if user still references it
-    // in other manifests
-    layersToDecrement := []LayerInfo{}
-
+    // Calculate quota impact (only new unique layers)
+    var quotaImpact int64
     for _, layer := range layers {
-        // Query: does this user have other manifests using this layer?
-        stillReferenced, err := db.CheckLayerReferencedByUser(
-            h.db, did, repository, layer.Digest, manifest.ID,
-        )
-
-        if err != nil {
-            http.Error(w, "failed to check layer references", 500)
-            return
+        if !existingSet[layer.Digest] {
+            quotaImpact += layer.Size
         }
+    }
 
-        if !stillReferenced {
-            // This layer is no longer used by user
-            layersToDecrement = append(layersToDecrement, LayerInfo{
-                Digest: layer.Digest,
-                Size:   layer.Size,
-            })
-        }
+    // Check quota
+    ok, current, err := r.quotaManager.CheckQuota(ctx, r.userDID, quotaImpact, r.quotaLimit)
+    if err != nil {
+        return err
+    }
+    if !ok {
+        return fmt.Errorf("quota exceeded: used=%d, impact=%d, limit=%d",
+            current, quotaImpact, r.quotaLimit)
     }
 
-    // Step 3: Delete manifest from user's PDS
-    atprotoClient := atproto.NewClient(manifest.PDSEndpoint, did, accessToken)
-    err = atprotoClient.DeleteRecord(ctx, atproto.ManifestCollection, manifestRKey)
+    // Store manifest in user's PDS
+    manifestURI, err := r.atprotoClient.PutManifest(ctx, manifest)
     if err != nil {
-        http.Error(w, "failed to delete from PDS", 500)
-        return
+        return err
     }
 
-    // Step 4: Notify hold service to decrement quota
-    if len(layersToDecrement) > 0 {
-        holdClient := &http.Client{}
-
-        decrementReq := QuotaDecrementRequest{
-            DID:    did,
-            Layers: layersToDecrement,
+    // Create layer records in hold's PDS
+    for _, layer := range layers {
+        record := LayerRecord{
+            Type:      "io.atcr.hold.layer",
+            Digest:    layer.Digest,
+            Size:      layer.Size,
+            MediaType: layer.MediaType,
+            Manifest:  manifestURI,
+            UserDID:   r.userDID,
+            CreatedAt: time.Now().Format(time.RFC3339),
         }
-
-        body, _ := json.Marshal(decrementReq)
-        resp, err := holdClient.Post(
-            manifest.HoldEndpoint + "/quota/decrement",
-            "application/json",
-            bytes.NewReader(body),
-        )
-
-        if err != nil || resp.StatusCode != 200 {
-            log.Printf("Warning: failed to update quota on hold service: %v", err)
-            // Continue anyway - GC reconciliation will fix it
+        if err := r.holdClient.CreateLayerRecord(ctx, record); err != nil {
+            log.Printf("Warning: failed to create layer record: %v", err)
+            // Continue - reconciliation will fix
         }
     }
 
-    // Step 5: Delete from AppView database
-    err = db.DeleteManifest(h.db, did, repository, digest)
-    if err != nil {
-        http.Error(w, "failed to delete from database", 500)
-        return
-    }
-
-    w.WriteHeader(http.StatusNoContent)
+    return nil
 }
 ```
 
-### Hold Service Decrement Endpoint
-
-```go
-// cmd/hold/main.go
-
-type QuotaDecrementRequest struct {
-    DID    string      `json:"did"`
-    Layers []LayerInfo `json:"layers"`
-}
+### Quota Check Timing
 
-type LayerInfo struct {
-    Digest string `json:"digest"`
-    Size   int64  `json:"size"`
-}
+Quota is checked when the **manifest is pushed** (after blobs are uploaded):
+- Blobs upload first via presigned URLs
+- Manifest pushed last triggers quota check
+- If quota exceeded, manifest is rejected (orphaned blobs cleaned by GC)
 
-func (s *HoldService) HandleQuotaDecrement(w http.ResponseWriter, r *http.Request) {
-    var req QuotaDecrementRequest
-    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
-        http.Error(w, "invalid request", 400)
-        return
-    }
+This matches Harbor's approach and is the industry standard.
 
-    // Read current quota
-    quota, err := s.quotaManager.GetQuota(req.DID)
-    if err != nil {
-        http.Error(w, "quota not found", 404)
-        return
-    }
+## Delete Flow
 
-    // Decrement quota for each layer
-    for _, layer := range req.Layers {
-        if size, claimed := quota.ClaimedLayers[layer.Digest]; claimed {
-            // Remove from claimed layers
-            delete(quota.ClaimedLayers, layer.Digest)
-            quota.Used -= size
+### Manifest Deletion
 
-            log.Printf("Decremented quota for %s: layer %s (%d bytes)",
-                req.DID, layer.Digest, size)
-        } else {
-            log.Printf("Warning: layer %s not in claimed_layers for %s",
-                layer.Digest, req.DID)
-        }
-    }
+When a user deletes a manifest:
 
-    // Ensure quota.Used doesn't go negative (defensive)
-    if quota.Used < 0 {
-        log.Printf("Warning: quota.Used went negative for %s, resetting to 0", req.DID)
-        quota.Used = 0
-    }
-
-    // Save updated quota
-    quota.LastUpdated = time.Now()
-    if err := s.quotaManager.SaveQuota(quota); err != nil {
-        http.Error(w, "failed to save quota", 500)
-        return
-    }
-
-    // Return updated quota info
-    json.NewEncoder(w).Encode(map[string]any{
-        "used":  quota.Used,
-        "limit": quota.Limit,
-    })
-}
 ```
-
-### SQL Query: Check Layer References
-
-```sql
--- pkg/appview/db/queries.go
-
--- Check if user still references this layer in other manifests
-SELECT COUNT(*)
-FROM layers l
-JOIN manifests m ON l.manifest_id = m.id
-WHERE m.did = ?           -- User's DID
-  AND l.digest = ?        -- Layer digest
-  AND m.id != ?           -- Exclude the manifest being deleted
+┌──────────┐          ┌──────────┐          ┌──────────┐          ┌──────────┐
+│   User   │          │ AppView  │          │   Hold   │          │ User PDS │
+│    UI    │          │          │          │ Service  │          │          │
+└──────────┘          └──────────┘          └──────────┘          └──────────┘
+     │                      │                      │                      │
+     │ DELETE manifest      │                      │                      │
+     ├─────────────────────>│                      │                      │
+     │                      │                      │                      │
+     │                      │ 1. Delete manifest   │                      │
+     │                      │    from user's PDS   │                      │
+     │                      ├──────────────────────┼─────────────────────>│
+     │                      │                      │                      │
+     │                      │ 2. Delete layer      │                      │
+     │                      │    records for this  │                      │
+     │                      │    manifest          │                      │
+     │                      ├─────────────────────>│                      │
+     │                      │                      │ 3. Remove records    │
+     │                      │                      │    where manifest    │
+     │                      │                      │    == deleted URI    │
+     │                      │                      │                      │
+     │ 4. 204 No Content    │                      │                      │
+     │<─────────────────────┤                      │                      │
 ```
 
-## Garbage Collection
-
-### Background: Orphaned Blobs
-
-Orphaned blobs accumulate when:
-1. Manifest push fails after blobs uploaded (presigned URLs bypass hold)
-2. Quota exceeded - manifest rejected, blobs already in S3
-3. User deletes manifest - blobs no longer referenced
-
-**GC periodically cleans these up.**
-
-### GC Cron Implementation
-
-Similar to AppView's backfill worker, the hold service can run periodic GC:
+### Implementation
 
 ```go
-// cmd/hold/gc/gc.go
+// pkg/appview/handlers/manifest.go
 
-type GarbageCollector struct {
-    driver      storagedriver.StorageDriver
-    appviewURL  string
-    holdURL     string
-    quotaManager *quota.Manager
-}
+func (h *ManifestHandler) DeleteManifest(w http.ResponseWriter, r *http.Request) {
+    userDID := auth.GetDID(r.Context())
+    repository := chi.URLParam(r, "repository")
+    digest := chi.URLParam(r, "digest")
 
-// Run garbage collection
-func (gc *GarbageCollector) Run(ctx context.Context) error {
-    log.Println("Starting garbage collection...")
+    // Get manifest URI before deletion
+    manifestURI := fmt.Sprintf("at://%s/%s/%s", userDID, ManifestCollection, digest)
 
-    // Step 1: Get list of referenced blobs from AppView
-    referenced, err := gc.getReferencedBlobs()
-    if err != nil {
-        return fmt.Errorf("failed to get referenced blobs: %w", err)
+    // Delete manifest from user's PDS
+    if err := h.atprotoClient.DeleteRecord(ctx, ManifestCollection, digest); err != nil {
+        http.Error(w, "failed to delete manifest", 500)
+        return
     }
 
-    referencedSet := make(map[string]bool)
-    for _, digest := range referenced {
-        referencedSet[digest] = true
+    // Delete associated layer records from hold's PDS
+    if err := h.holdClient.DeleteLayerRecords(ctx, manifestURI); err != nil {
+        log.Printf("Warning: failed to delete layer records: %v", err)
+        // Continue - reconciliation will clean up
     }
 
-    log.Printf("AppView reports %d referenced blobs", len(referenced))
-
-    // Step 2: Walk S3 blobs
-    deletedCount := 0
-    reclaimedBytes := int64(0)
-
-    err = gc.driver.Walk(ctx, "/docker/registry/v2/blobs", func(fileInfo storagedriver.FileInfo) error {
-        if fileInfo.IsDir() {
-            return nil  // Skip directories
-        }
-
-        // Extract digest from path
-        // Path: /docker/registry/v2/blobs/sha256/ab/abc123.../data
-        digest := extractDigestFromPath(fileInfo.Path())
-
-        if !referencedSet[digest] {
-            // Unreferenced blob - delete it
-            size := fileInfo.Size()
-
-            if err := gc.driver.Delete(ctx, fileInfo.Path()); err != nil {
-                log.Printf("Failed to delete blob %s: %v", digest, err)
-                return nil  // Continue anyway
-            }
-
-            deletedCount++
-            reclaimedBytes += size
-
-            log.Printf("GC: Deleted unreferenced blob %s (%d bytes)", digest, size)
-        }
-
-        return nil
-    })
-
-    if err != nil {
-        return fmt.Errorf("failed to walk blobs: %w", err)
-    }
-
-    log.Printf("GC complete: deleted %d blobs, reclaimed %d bytes",
-        deletedCount, reclaimedBytes)
-
-    return nil
-}
-
-// Get referenced blobs from AppView
-func (gc *GarbageCollector) getReferencedBlobs() ([]string, error) {
-    // Query AppView for all blobs referenced by manifests
-    // stored in THIS hold service
-    url := fmt.Sprintf("%s/internal/blobs/referenced?hold=%s",
-        gc.appviewURL, url.QueryEscape(gc.holdURL))
-
-    resp, err := http.Get(url)
-    if err != nil {
-        return nil, err
-    }
-    defer resp.Body.Close()
-
-    var result struct {
-        Blobs []string `json:"blobs"`
-    }
-
-    if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
-        return nil, err
-    }
-
-    return result.Blobs, nil
+    w.WriteHeader(http.StatusNoContent)
 }
 ```
 
-### AppView Internal API
+### Hold Service: Delete Layer Records
 
 ```go
-// pkg/appview/handlers/internal.go
+// pkg/hold/pds/xrpc.go
 
-// Get all referenced blobs for a specific hold
-func (h *InternalHandler) GetReferencedBlobs(w http.ResponseWriter, r *http.Request) {
-    holdEndpoint := r.URL.Query().Get("hold")
-    if holdEndpoint == "" {
-        http.Error(w, "missing hold parameter", 400)
-        return
-    }
-
-    // Query database for all layers in manifests stored in this hold
-    query := `
-        SELECT DISTINCT l.digest
-        FROM layers l
-        JOIN manifests m ON l.manifest_id = m.id
-        WHERE m.hold_endpoint = ?
-    `
-
-    rows, err := h.db.Query(query, holdEndpoint)
+func (s *Server) DeleteLayerRecords(ctx context.Context, manifestURI string) error {
+    // List all layer records
+    records, err := s.ListRecords(ctx, LayerCollection, "")
     if err != nil {
-        http.Error(w, "database error", 500)
-        return
+        return err
     }
-    defer rows.Close()
 
-    blobs := []string{}
-    for rows.Next() {
-        var digest string
-        if err := rows.Scan(&digest); err != nil {
+    // Delete records matching this manifest
+    for _, record := range records {
+        var layer LayerRecord
+        if err := json.Unmarshal(record.Value, &layer); err != nil {
             continue
         }
-        blobs = append(blobs, digest)
-    }
-
-    json.NewEncoder(w).Encode(map[string]any{
-        "blobs": blobs,
-        "count": len(blobs),
-        "hold":  holdEndpoint,
-    })
-}
-```
-
-### GC Cron Schedule
-
-```go
-// cmd/hold/main.go
-
-func main() {
-    // ... service setup ...
-
-    // Start GC cron if enabled
-    if os.Getenv("GC_ENABLED") == "true" {
-        gcInterval := 24 * time.Hour  // Daily by default
-
-        go func() {
-            ticker := time.NewTicker(gcInterval)
-            defer ticker.Stop()
-
-            for range ticker.C {
-                if err := garbageCollector.Run(context.Background()); err != nil {
-                    log.Printf("GC error: %v", err)
-                }
+        if layer.Manifest == manifestURI {
+            if err := s.DeleteRecord(ctx, LayerCollection, record.RKey); err != nil {
+                log.Printf("Failed to delete layer record %s: %v", record.RKey, err)
             }
-        }()
-
-        log.Printf("GC cron started: runs every %v", gcInterval)
+        }
     }
 
-    // Start server...
+    return nil
 }
 ```
 
-## Quota Reconciliation
+### Quota After Deletion
 
-### PDS as Source of Truth
+After deleting a manifest:
+- Layer records for that manifest are removed
+- Quota recalculated with `SELECT DISTINCT` query
+- If layer was only in deleted manifest → quota decreases
+- If layer exists in other manifests → quota unchanged (still deduplicated)
 
-**Key insight:** Manifest records in PDS are publicly readable (no OAuth needed for reads).
+## Garbage Collection
 
-Each manifest contains:
-- Repository name
-- Digest
-- Layers array with digest + size
-- Hold endpoint
+### Orphaned Blobs
 
-The hold service can query the PDS to calculate the user's true quota:
+Orphaned blobs accumulate when:
+1. Manifest push fails after blobs uploaded
+2. Quota exceeded - manifest rejected
+3. User deletes manifest - blobs may no longer be referenced
 
-```
-1. List all io.atcr.manifest records for user
-2. Filter manifests where holdEndpoint == this hold service
-3. Extract unique layers (deduplicate by digest)
-4. Sum layer sizes = true quota usage
-5. Compare to quota file
-6. Fix discrepancies
-```
-
-### Implementation
+### GC Process
 
 ```go
-// cmd/hold/quota/reconcile.go
+// pkg/hold/gc/gc.go
 
-type Reconciler struct {
-    quotaManager    *Manager
-    atprotoResolver *atproto.Resolver
-    holdURL         string
-}
-
-// ReconcileUser recalculates quota from PDS manifests
-func (r *Reconciler) ReconcileUser(ctx context.Context, did string) error {
-    log.Printf("Reconciling quota for %s", did)
-
-    // Step 1: Resolve user's PDS endpoint
-    identity, err := r.atprotoResolver.ResolveIdentity(ctx, did)
+func (gc *GarbageCollector) Run(ctx context.Context) error {
+    // Step 1: Get all referenced digests from layer records
+    records, err := gc.pds.ListRecords(ctx, LayerCollection, "")
     if err != nil {
-        return fmt.Errorf("failed to resolve DID: %w", err)
+        return err
     }
 
-    // Step 2: Create unauthenticated ATProto client
-    // (manifest records are public - no OAuth needed)
-    client := atproto.NewClient(identity.PDSEndpoint, did, "")
-
-    // Step 3: List all manifest records for this user
-    manifests, err := client.ListRecords(ctx, atproto.ManifestCollection, 1000)
-    if err != nil {
-        return fmt.Errorf("failed to list manifests: %w", err)
-    }
-
-    // Step 4: Filter manifests stored in THIS hold service
-    // and extract unique layers
-    uniqueLayers := make(map[string]int64)  // digest -> size
-
-    for _, record := range manifests {
-        var manifest atproto.ManifestRecord
-        if err := json.Unmarshal(record.Value, &manifest); err != nil {
-            log.Printf("Warning: failed to parse manifest: %v", err)
-            continue
-        }
-
-        // Only count manifests stored in this hold
-        if manifest.HoldEndpoint != r.holdURL {
+    referenced := make(map[string]bool)
+    for _, record := range records {
+        var layer LayerRecord
+        if err := json.Unmarshal(record.Value, &layer); err != nil {
             continue
         }
-
-        // Add config blob
-        if manifest.Config.Digest != "" {
-            uniqueLayers[manifest.Config.Digest] = manifest.Config.Size
-        }
-
-        // Add layer blobs
-        for _, layer := range manifest.Layers {
-            uniqueLayers[layer.Digest] = layer.Size
-        }
+        referenced[layer.Digest] = true
     }
 
-    // Step 5: Calculate true quota usage
-    trueUsage := int64(0)
-    for _, size := range uniqueLayers {
-        trueUsage += size
-    }
-
-    log.Printf("User %s true usage from PDS: %d bytes (%d unique layers)",
-        did, trueUsage, len(uniqueLayers))
+    log.Printf("Found %d referenced blobs", len(referenced))
 
-    // Step 6: Compare with current quota file
-    quota, err := r.quotaManager.GetQuota(did)
-    if err != nil {
-        log.Printf("No existing quota for %s, creating new", did)
-        quota = &Quota{
-            DID:           did,
-            Limit:         r.quotaManager.DefaultLimit,
-            ClaimedLayers: make(map[string]int64),
+    // Step 2: Walk S3 blobs and delete unreferenced
+    var deleted, reclaimed int64
+    err = gc.driver.Walk(ctx, "/docker/registry/v2/blobs", func(fi storagedriver.FileInfo) error {
+        if fi.IsDir() {
+            return nil
         }
-    }
 
-    // Step 7: Fix discrepancies
-    if quota.Used != trueUsage || len(quota.ClaimedLayers) != len(uniqueLayers) {
-        log.Printf("Quota mismatch for %s: recorded=%d, actual=%d (diff=%d)",
-            did, quota.Used, trueUsage, trueUsage - quota.Used)
-
-        // Update quota to match PDS truth
-        quota.Used = trueUsage
-        quota.ClaimedLayers = uniqueLayers
-        quota.LastUpdated = time.Now()
-
-        if err := r.quotaManager.SaveQuota(quota); err != nil {
-            return fmt.Errorf("failed to save reconciled quota: %w", err)
-        }
-
-        log.Printf("Reconciled quota for %s: %d bytes", did, trueUsage)
-    } else {
-        log.Printf("Quota for %s is accurate", did)
-    }
-
-    return nil
-}
-
-// ReconcileAll reconciles all users (run periodically)
-func (r *Reconciler) ReconcileAll(ctx context.Context) error {
-    // Get list of all users with quota files
-    users, err := r.quotaManager.ListUsers()
-    if err != nil {
-        return err
-    }
-
-    log.Printf("Starting reconciliation for %d users", len(users))
-
-    for _, did := range users {
-        if err := r.ReconcileUser(ctx, did); err != nil {
-            log.Printf("Failed to reconcile %s: %v", did, err)
-            // Continue with other users
+        digest := extractDigestFromPath(fi.Path())
+        if !referenced[digest] {
+            size := fi.Size()
+            if err := gc.driver.Delete(ctx, fi.Path()); err != nil {
+                log.Printf("Failed to delete %s: %v", digest, err)
+                return nil
+            }
+            deleted++
+            reclaimed += size
+            log.Printf("GC: deleted %s (%d bytes)", digest, size)
         }
-    }
+        return nil
+    })
 
-    log.Println("Reconciliation complete")
-    return nil
+    log.Printf("GC complete: deleted %d blobs, reclaimed %d bytes", deleted, reclaimed)
+    return err
 }
 ```
 
-### Reconciliation Cron
-
-```go
-// cmd/hold/main.go
-
-func main() {
-    // ... setup ...
-
-    // Start reconciliation cron
-    if os.Getenv("QUOTA_RECONCILE_ENABLED") == "true" {
-        reconcileInterval := 24 * time.Hour  // Daily
-
-        go func() {
-            ticker := time.NewTicker(reconcileInterval)
-            defer ticker.Stop()
-
-            for range ticker.C {
-                if err := reconciler.ReconcileAll(context.Background()); err != nil {
-                    log.Printf("Reconciliation error: %v", err)
-                }
-            }
-        }()
+### GC Schedule
 
-        log.Printf("Quota reconciliation cron started: runs every %v", reconcileInterval)
-    }
-
-    // ... start server ...
-}
+```bash
+# Environment variable
+GC_ENABLED=true
+GC_INTERVAL=24h  # Daily by default
 ```
 
-### Why PDS as Source of Truth Works
-
-1. **Manifests are canonical** - If manifest exists in PDS, user owns those layers
-2. **Public reads** - No OAuth needed, just resolve DID → PDS endpoint
-3. **ATProto durability** - PDS is user's authoritative data store
-4. **AppView is cache** - AppView database might lag or have inconsistencies
-5. **Reconciliation fixes drift** - Periodic sync from PDS ensures accuracy
-
-**Example reconciliation scenarios:**
-
-- **Orphaned quota entries:** User deleted manifest from PDS, but hold quota still has it
-  → Reconciliation removes from claimed_layers
-
-- **Missing quota entries:** User pushed manifest, but quota update failed
-  → Reconciliation adds to claimed_layers
-
-- **Race condition duplicates:** Two concurrent pushes double-counted a layer
-  → Reconciliation fixes to actual usage
-
 ## Configuration
 
 ### Hold Service Environment Variables
···
 ```bash
 # .env.hold
 
-# ============================================================================
 # Quota Configuration
-# ============================================================================
-
-# Enable quota enforcement
 QUOTA_ENABLED=true
-
-# Default quota limit per user (bytes)
-# 10GB = 10737418240
-# 50GB = 53687091200
-# 100GB = 107374182400
-QUOTA_DEFAULT_LIMIT=10737418240
-
-# Storage backend for quota data
-# Options: s3, sqlite
-QUOTA_STORAGE_BACKEND=s3
-
-# For S3-based storage:
-# Quota files stored in same bucket as blobs
-QUOTA_STORAGE_PREFIX=/atcr/quota/
+QUOTA_DEFAULT_LIMIT=10737418240  # 10GB in bytes
 
-# For SQLite-based storage:
-QUOTA_DB_PATH=/var/lib/atcr/hold-quota.db
-
-# ============================================================================
 # Garbage Collection
-# ============================================================================
-
-# Enable periodic garbage collection
 GC_ENABLED=true
-
-# GC interval (default: 24h)
 GC_INTERVAL=24h
-
-# AppView URL for GC reference checking
-APPVIEW_URL=https://atcr.io
-
-# ============================================================================
-# Quota Reconciliation
-# ============================================================================
-
-# Enable quota reconciliation from PDS
-QUOTA_RECONCILE_ENABLED=true
-
-# Reconciliation interval (default: 24h)
-QUOTA_RECONCILE_INTERVAL=24h
-
-# ============================================================================
-# Hold Service Identity (Required)
-# ============================================================================
-
-# Public URL of this hold service
-HOLD_PUBLIC_URL=https://hold1.example.com
-
-# Owner DID (for auto-registration)
-HOLD_OWNER=did:plc:xyz123
 ```
 
-### AppView Configuration
+### Quota Limits by Bytes
 
-```bash
-# .env.appview
-
-# Internal API endpoint for hold services
-# Used for GC reference checking
-ATCR_INTERNAL_API_ENABLED=true
-
-# Optional: authentication token for internal APIs
-ATCR_INTERNAL_API_TOKEN=secret123
-```
-
-## Trade-offs & Design Decisions
-
-### 1. Claimed Storage vs Physical Storage
-
-**Decision:** Track claimed storage (logical accounting)
-
-**Why:**
-- Predictable for users: "you pay for what you upload"
-- No complex cross-user dependencies
-- Delete always gives you quota back
-- Matches Harbor's proven model
-
-**Trade-off:**
-- Total claimed can exceed physical storage
-- Users might complain "I uploaded 10GB but S3 only has 6GB"
-
-**Mitigation:**
-- Show deduplication savings metric
-- Educate users: "You claimed 10GB, but deduplication saved 4GB"
-
-### 2. S3 vs SQLite for Quota Storage
-
-**Decision:** Support both, recommend based on use case
-
-**S3 Pros:**
-- No database to manage
-- Quota data lives with blobs
-- Better for ephemeral BYOS
-
-**SQLite Pros:**
-- Faster (no network)
-- ACID transactions (no race conditions)
-- Better for high-traffic shared holds
-
-**Trade-off:**
-- S3: eventual consistency, race conditions
-- SQLite: stateful service, scaling challenges
-
-**Mitigation:**
-- Reconciliation fixes S3 inconsistencies
-- SQLite can use shared DB for multi-instance
-
-### 3. Optimistic Quota Update
-
-**Decision:** Update quota BEFORE upload completes
-
-**Why:**
-- Prevent race conditions (two users uploading simultaneously)
-- Can reject before presigned URL generated
-- Simpler flow
-
-**Trade-off:**
-- If upload fails, quota already incremented (user "paid" for nothing)
-
-**Mitigation:**
-- Reconciliation from PDS fixes orphaned quota entries
-- Acceptable for MVP (upload failures are rare)
-
-### 4. AppView as Intermediary
-
-**Decision:** AppView notifies hold service on deletes
-
-**Why:**
-- AppView already has manifest/layer database
-- Can efficiently check if layer still referenced
-- Hold service doesn't need to query PDS on every delete
-
-**Trade-off:**
-- AppView → Hold dependency
-- Network hop on delete
-
-**Mitigation:**
-- If notification fails, reconciliation fixes quota
-- Eventually consistent is acceptable
-
-### 5. PDS as Source of Truth
-
-**Decision:** Use PDS manifests for reconciliation
-
-**Why:**
-- Manifests in PDS are canonical user data
-- Public reads (no OAuth for reconciliation)
-- AppView database might lag or be inconsistent
-
-**Trade-off:**
-- Reconciliation requires PDS queries (slower)
-- Limited to 1000 manifests per query
-
-**Mitigation:**
-- Run reconciliation daily (not real-time)
-- Paginate if user has >1000 manifests
+| Size | Bytes |
+|------|-------|
+| 1 GB | 1073741824 |
+| 5 GB | 5368709120 |
+| 10 GB | 10737418240 |
+| 50 GB | 53687091200 |
+| 100 GB | 107374182400 |
 
 ## Future Enhancements
 
 ### 1. Quota API Endpoints
 
 ```
-GET  /quota/usage                  - Get current user's quota
-GET  /quota/breakdown              - Get storage by repository
-POST /quota/limit                  - Update user's quota limit (admin)
-GET  /quota/stats                  - Get hold-wide statistics
+GET  /xrpc/io.atcr.hold.getQuota?did={userDID}  - Get user's quota usage
+GET  /xrpc/io.atcr.hold.getQuotaBreakdown       - Storage by repository
 ```
 
 ### 2. Quota Alerts
 
-Notify users when approaching limit:
-- Email/webhook at 80%, 90%, 95%
-- Reject uploads at 100% (currently implemented)
-- Grace period: allow 105% temporarily
+- Warning thresholds at 80%, 90%, 95%
+- Email/webhook notifications
+- Grace period before hard enforcement
 
 ### 3. Tiered Quotas
 
-Different limits based on user tier:
-- Free: 10GB
-- Pro: 100GB
-- Enterprise: unlimited
-
-### 4. Quota Purchasing
-
-Allow users to buy additional storage:
-- Stripe integration
-- $0.10/GB/month pricing
-- Dynamic limit updates
-
-### 5. Cross-Hold Deduplication
-
-If multiple holds share same S3 bucket:
-- Track blob ownership globally
-- Split costs proportionally
-- More complex, but maximizes deduplication
-
-### 6. Manifest-Based Quota (Alternative Model)
-
-Instead of tracking layers, track manifests:
-- Simpler: just count manifest sizes
-- No deduplication benefits for users
-- Might be acceptable for some use cases
-
-### 7. Redis-Based Quota (High Performance)
-
-For high-traffic registries:
-- Use Redis instead of S3/SQLite
-- Sub-millisecond quota checks
-- Harbor-proven approach
-
-### 8. Quota Visualizations
-
-Web UI showing:
-- Storage usage over time
-- Top consumers by repository
-- Deduplication savings graph
-- Layer size distribution
+| Tier | Limit |
+|------|-------|
+| Free | 10 GB |
+| Pro | 100 GB |
+| Enterprise | Unlimited |
 
-## Appendix: SQL Queries
+### 4. Rate Limiting
 
-### Check if User Still References Layer
+Pull rate limits (Docker Hub style):
+- Anonymous: 100 pulls per 6 hours per IP
+- Authenticated: 200 pulls per 6 hours
+- Paid: Unlimited
 
-```sql
--- After deleting manifest, check if user has other manifests using this layer
-SELECT COUNT(*)
-FROM layers l
-JOIN manifests m ON l.manifest_id = m.id
-WHERE m.did = ?           -- User's DID
-  AND l.digest = ?        -- Layer digest to check
-  AND m.id != ?           -- Exclude the manifest being deleted
-```
+### 5. Quota Purchasing
 
-### Get All Unique Layers for User
-
-```sql
--- Calculate true quota usage for a user
-SELECT DISTINCT l.digest, l.size
-FROM layers l
-JOIN manifests m ON l.manifest_id = m.id
-WHERE m.did = ?
-  AND m.hold_endpoint = ?
-```
-
-### Get Referenced Blobs for Hold
-
-```sql
--- For GC: get all blobs still referenced by any user of this hold
-SELECT DISTINCT l.digest
-FROM layers l
-JOIN manifests m ON l.manifest_id = m.id
-WHERE m.hold_endpoint = ?
-```
-
-### Get Storage Stats by Repository
-
-```sql
--- User's storage broken down by repository
-SELECT
-    m.repository,
-    COUNT(DISTINCT m.id) as manifest_count,
-    COUNT(DISTINCT l.digest) as unique_layers,
-    SUM(l.size) as total_size
-FROM manifests m
-JOIN layers l ON l.manifest_id = m.id
-WHERE m.did = ?
-  AND m.hold_endpoint = ?
-GROUP BY m.repository
-ORDER BY total_size DESC
-```
+- Stripe integration for additional storage
+- $0.10/GB/month pricing (industry standard)
 
 ## References
 
 - **Harbor Quotas:** https://goharbor.io/docs/1.10/administration/configure-project-quotas/
-- **Harbor Source:** https://github.com/goharbor/harbor
 - **ATProto Spec:** https://atproto.com/specs/record
 - **OCI Distribution Spec:** https://github.com/opencontainers/distribution-spec
-- **S3 API Reference:** https://docs.aws.amazon.com/AmazonS3/latest/API/
-- **Distribution GC:** https://github.com/distribution/distribution/blob/main/registry/storage/garbagecollect.go
 
 ---
 
-**Document Version:** 1.0
-**Last Updated:** 2025-10-09
-**Author:** Generated from implementation research and Harbor analysis
+**Document Version:** 2.0
+**Last Updated:** 2026-01-04
+**Model:** Per-user layer tracking with ATProto records

lexicons/io/atcr/hold/layer.json

···
       "description": "Represents metadata about a container layer stored in the hold. Stored in the hold's embedded PDS for tracking and analytics.",
       "record": {
         "type": "object",
-        "required": ["digest", "size", "mediaType", "repository", "userDid", "userHandle", "createdAt"],
+        "required": ["digest", "size", "mediaType", "manifest", "userDid", "createdAt"],
         "properties": {
           "digest": {
             "type": "string",
···
             "description": "Media type (e.g., application/vnd.oci.image.layer.v1.tar+gzip)",
             "maxLength": 128
           },
-          "repository": {
+          "manifest": {
             "type": "string",
-            "description": "Repository this layer belongs to",
-            "maxLength": 255
+            "format": "at-uri",
+            "description": "AT-URI of the manifest that included this layer (e.g., at://did:plc:xyz/io.atcr.manifest/abc123)"
           },
           "userDid": {
             "type": "string",
             "format": "did",
             "description": "DID of user who uploaded this layer"
-          },
-          "userHandle": {
-            "type": "string",
-            "format": "handle",
-            "description": "Handle of user (for display purposes)"
           },
           "createdAt": {
             "type": "string",

pkg/appview/handlers/storage.go

···
+package handlers
+
+import (
+	"encoding/json"
+	"fmt"
+	"html/template"
+	"log/slog"
+	"net/http"
+
+	"atcr.io/pkg/appview/middleware"
+	"atcr.io/pkg/appview/storage"
+	"atcr.io/pkg/atproto"
+	"atcr.io/pkg/auth/oauth"
+)
+
+// StorageHandler handles the storage quota API endpoint
+// Returns an HTML partial for HTMX to swap into the settings page
+type StorageHandler struct {
+	Templates *template.Template
+	Refresher *oauth.Refresher
+}
+
+// QuotaStats mirrors the hold service response
+type QuotaStats struct {
+	UserDID     string `json:"userDid"`
+	UniqueBlobs int    `json:"uniqueBlobs"`
+	TotalSize   int64  `json:"totalSize"`
+}
+
+func (h *StorageHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	user := middleware.GetUser(r)
+	if user == nil {
+		http.Error(w, "Unauthorized", http.StatusUnauthorized)
+		return
+	}
+
+	// Create ATProto client with session provider
+	client := atproto.NewClientWithSessionProvider(user.PDSEndpoint, user.DID, h.Refresher)
+
+	// Get user's sailor profile to find their default hold
+	profile, err := storage.GetProfile(r.Context(), client)
+	if err != nil {
+		slog.Warn("Failed to get profile for storage quota", "did", user.DID, "error", err)
+		h.renderError(w, "Failed to load profile")
+		return
+	}
+
+	if profile == nil || profile.DefaultHold == "" {
+		// No default hold configured - can't check quota
+		h.renderNoHold(w)
+		return
+	}
+
+	// Resolve hold URL from DID
+	holdURL := atproto.ResolveHoldURL(profile.DefaultHold)
+	if holdURL == "" {
+		slog.Warn("Failed to resolve hold URL", "did", user.DID, "holdDid", profile.DefaultHold)
+		h.renderError(w, "Failed to resolve hold service")
+		return
+	}
+
+	// Call the hold's quota endpoint
+	quotaURL := fmt.Sprintf("%s%s?userDid=%s", holdURL, atproto.HoldGetQuota, user.DID)
+	resp, err := http.Get(quotaURL)
+	if err != nil {
+		slog.Warn("Failed to fetch quota from hold", "did", user.DID, "holdURL", holdURL, "error", err)
+		h.renderError(w, "Failed to connect to hold service")
+		return
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		slog.Warn("Hold returned error for quota", "did", user.DID, "status", resp.StatusCode)
+		h.renderError(w, "Hold service returned an error")
+		return
+	}
+
+	var stats QuotaStats
+	if err := json.NewDecoder(resp.Body).Decode(&stats); err != nil {
+		slog.Warn("Failed to decode quota response", "did", user.DID, "error", err)
+		h.renderError(w, "Failed to parse quota data")
+		return
+	}
+
+	// Render the stats partial
+	h.renderStats(w, stats)
+}
+
+func (h *StorageHandler) renderStats(w http.ResponseWriter, stats QuotaStats) {
+	data := struct {
+		UniqueBlobs int
+		TotalSize   int64
+		HumanSize   string
+	}{
+		UniqueBlobs: stats.UniqueBlobs,
+		TotalSize:   stats.TotalSize,
+		HumanSize:   humanizeBytes(stats.TotalSize),
+	}
+
+	w.Header().Set("Content-Type", "text/html")
+	if err := h.Templates.ExecuteTemplate(w, "storage_stats", data); err != nil {
+		slog.Error("Failed to render storage stats template", "error", err)
+		http.Error(w, "Failed to render template", http.StatusInternalServerError)
+	}
+}
+
+func (h *StorageHandler) renderError(w http.ResponseWriter, message string) {
+	w.Header().Set("Content-Type", "text/html")
+	fmt.Fprintf(w, `<div class="storage-error"><i data-lucide="alert-circle"></i> %s</div>`, message)
+}
+
+func (h *StorageHandler) renderNoHold(w http.ResponseWriter) {
+	w.Header().Set("Content-Type", "text/html")
+	fmt.Fprint(w, `<div class="storage-info"><i data-lucide="info"></i> No hold configured. Set a default hold above to see storage usage.</div>`)
+}
+
+// humanizeBytes converts bytes to human-readable format
+func humanizeBytes(bytes int64) string {
+	const unit = 1024
+	if bytes < unit {
+		return fmt.Sprintf("%d B", bytes)
+	}
+	div, exp := int64(unit), 0
+	for n := bytes / unit; n >= unit; n /= unit {
+		div *= unit
+		exp++
+	}
+	return fmt.Sprintf("%.1f %cB", float64(bytes)/float64(div), "KMGTPE"[exp])
+}

pkg/appview/routes/routes.go

···
 			RegistryURL: registryURL,
 		}).ServeHTTP)
 
+		r.Get("/api/storage", (&uihandlers.StorageHandler{
+			Templates: deps.Templates,
+			Refresher: deps.Refresher,
+		}).ServeHTTP)
+
 		r.Post("/api/profile/default-hold", (&uihandlers.UpdateDefaultHoldHandler{
 			Refresher: deps.Refresher,
 		}).ServeHTTP)

pkg/appview/storage/manifest_store.go

···
 	serviceToken := s.ctx.ServiceToken
 
 	// Build notification request
+	// Note: userHandle is resolved from userDid on the hold side (cached, 24-hour TTL)
 	notifyReq := map[string]any{
-		"repository": s.ctx.Repository,
-		"userDid":    s.ctx.DID,
-		"userHandle": s.ctx.Handle,
-		"operation":  operation,
+		"repository":     s.ctx.Repository,
+		"userDid":        s.ctx.DID,
+		"manifestDigest": manifestDigest,
+		"operation":      operation,
 	}
 
 	// For push operations, include full manifest data

pkg/appview/templates/pages/settings.html

···
         </div>
     </section>
 
+    <!-- Storage Usage Section -->
+    <section class="settings-section storage-section">
+        <h2>Storage Usage</h2>
+        <p>Estimated storage usage on your default hold.</p>
+        <div id="storage-stats" hx-get="/api/storage" hx-trigger="load" hx-swap="innerHTML">
+            <p><i data-lucide="loader-2" class="spin"></i> Loading...</p>
+        </div>
+    </section>
+
     <!-- Default Hold Section -->
     <section class="settings-section">
         <h2>Default Hold</h2>
···
     </script>
 
     <style>
+    /* Storage Section Styles */
+    .storage-section .storage-stats {
+        background: var(--code-bg);
+        padding: 1rem;
+        border-radius: 4px;
+        margin-top: 0.5rem;
+    }
+    .storage-section .stat-row {
+        display: flex;
+        justify-content: space-between;
+        padding: 0.5rem 0;
+        border-bottom: 1px solid var(--border);
+    }
+    .storage-section .stat-row:last-child {
+        border-bottom: none;
+    }
+    .storage-section .stat-label {
+        color: var(--fg-muted);
+    }
+    .storage-section .stat-value {
+        font-weight: bold;
+        font-family: monospace;
+    }
+    .storage-section .storage-error,
+    .storage-section .storage-info {
+        padding: 1rem;
+        border-radius: 4px;
+        margin-top: 0.5rem;
+        display: flex;
+        align-items: center;
+        gap: 0.5rem;
+    }
+    .storage-section .storage-error {
+        background: var(--error-bg, #fef2f2);
+        color: var(--error, #dc2626);
+        border: 1px solid var(--error, #dc2626);
+    }
+    .storage-section .storage-info {
+        background: var(--info-bg, #eff6ff);
+        color: var(--info, #2563eb);
+        border: 1px solid var(--info, #2563eb);
+    }
+    .spin {
+        animation: spin 1s linear infinite;
+    }
+    @keyframes spin {
+        from { transform: rotate(0deg); }
+        to { transform: rotate(360deg); }
+    }
+
     /* Devices Section Styles */
     .devices-section .setup-instructions {
         margin: 1rem 0;

pkg/appview/templates/partials/storage_stats.html

···
+{{ define "storage_stats" }}
+<div class="storage-stats">
+    <div class="stat-row">
+        <span class="stat-label">Unique Blobs:</span>
+        <span class="stat-value">{{ .UniqueBlobs }}</span>
+    </div>
+    <div class="stat-row">
+        <span class="stat-label">Total Storage:</span>
+        <span class="stat-value">{{ .HumanSize }}</span>
+    </div>
+</div>
+{{ end }}

pkg/atproto/cbor_gen.go

···
 
 	cw := cbg.NewCborWriter(w)
 
-	if _, err := cw.Write([]byte{168}); err != nil {
+	if _, err := cw.Write([]byte{167}); err != nil {
 		return err
 	}
 
···
 		return err
 	}
 
+	// t.Manifest (string) (string)
+	if len("manifest") > 8192 {
+		return xerrors.Errorf("Value in field \"manifest\" was too long")
+	}
+
+	if err := cw.WriteMajorTypeHeader(cbg.MajTextString, uint64(len("manifest"))); err != nil {
+		return err
+	}
+	if _, err := cw.WriteString(string("manifest")); err != nil {
+		return err
+	}
+
+	if len(t.Manifest) > 8192 {
+		return xerrors.Errorf("Value in field t.Manifest was too long")
+	}
+
+	if err := cw.WriteMajorTypeHeader(cbg.MajTextString, uint64(len(t.Manifest))); err != nil {
+		return err
+	}
+	if _, err := cw.WriteString(string(t.Manifest)); err != nil {
+		return err
+	}
+
 	// t.CreatedAt (string) (string)
 	if len("createdAt") > 8192 {
 		return xerrors.Errorf("Value in field \"createdAt\" was too long")
···
 	if _, err := cw.WriteString(string(t.MediaType)); err != nil {
 		return err
 	}
-
-	// t.Repository (string) (string)
-	if len("repository") > 8192 {
-		return xerrors.Errorf("Value in field \"repository\" was too long")
-	}
-
-	if err := cw.WriteMajorTypeHeader(cbg.MajTextString, uint64(len("repository"))); err != nil {
-		return err
-	}
-	if _, err := cw.WriteString(string("repository")); err != nil {
-		return err
-	}
-
-	if len(t.Repository) > 8192 {
-		return xerrors.Errorf("Value in field t.Repository was too long")
-	}
-
-	if err := cw.WriteMajorTypeHeader(cbg.MajTextString, uint64(len(t.Repository))); err != nil {
-		return err
-	}
-	if _, err := cw.WriteString(string(t.Repository)); err != nil {
-		return err
-	}
-
-	// t.UserHandle (string) (string)
-	if len("userHandle") > 8192 {
-		return xerrors.Errorf("Value in field \"userHandle\" was too long")
-	}
-
-	if err := cw.WriteMajorTypeHeader(cbg.MajTextString, uint64(len("userHandle"))); err != nil {
-		return err
-	}
-	if _, err := cw.WriteString(string("userHandle")); err != nil {
-		return err
-	}
-
-	if len(t.UserHandle) > 8192 {
-		return xerrors.Errorf("Value in field t.UserHandle was too long")
-	}
-
-	if err := cw.WriteMajorTypeHeader(cbg.MajTextString, uint64(len(t.UserHandle))); err != nil {
-		return err
-	}
-	if _, err := cw.WriteString(string(t.UserHandle)); err != nil {
-		return err
-	}
 	return nil
 }
 
···
 
 	n := extra
 
-	nameBuf := make([]byte, 10)
+	nameBuf := make([]byte, 9)
 	for i := uint64(0); i < n; i++ {
 		nameLen, ok, err := cbg.ReadFullStringIntoBuf(cr, nameBuf, 8192)
 		if err != nil {
···
 
 				t.UserDID = string(sval)
 			}
+			// t.Manifest (string) (string)
+		case "manifest":
+
+			{
+				sval, err := cbg.ReadStringWithMax(cr, 8192)
+				if err != nil {
+					return err
+				}
+
+				t.Manifest = string(sval)
+			}
 			// t.CreatedAt (string) (string)
 		case "createdAt":
 
···
 				}
 
 				t.MediaType = string(sval)
-			}
-			// t.Repository (string) (string)
-		case "repository":
-
-			{
-				sval, err := cbg.ReadStringWithMax(cr, 8192)
-				if err != nil {
-					return err
-				}
-
-				t.Repository = string(sval)
-			}
-			// t.UserHandle (string) (string)
-		case "userHandle":
-
-			{
-				sval, err := cbg.ReadStringWithMax(cr, 8192)
-				if err != nil {
-					return err
-				}
-
-				t.UserHandle = string(sval)
 			}
 
 		default:

pkg/atproto/endpoints.go

···
 	// Request: {"ownerDid": "...", "repository": "...", "pullCount": 10, "pushCount": 5, "lastPull": "...", "lastPush": "..."}
 	// Response: {"success": true}
 	HoldSetStats = "/xrpc/io.atcr.hold.setStats"
+
+	// HoldGetQuota returns storage quota information for a user.
+	// Method: GET
+	// Query: userDid={did}
+	// Response: {"userDid": "...", "uniqueBlobs": 10, "totalSize": 1073741824}
+	HoldGetQuota = "/xrpc/io.atcr.hold.getQuota"
 )
 
 // Hold service crew management endpoints (io.atcr.hold.*)

pkg/atproto/lexicon.go

···
 // Stored in the hold's embedded PDS for tracking and analytics
 // Uses CBOR encoding for efficient storage in hold's carstore
 type LayerRecord struct {
-	Type       string `json:"$type" cborgen:"$type"`
-	Digest     string `json:"digest" cborgen:"digest"`         // Layer digest (e.g., "sha256:abc123...")
-	Size       int64  `json:"size" cborgen:"size"`             // Size in bytes
-	MediaType  string `json:"mediaType" cborgen:"mediaType"`   // Media type (e.g., "application/vnd.oci.image.layer.v1.tar+gzip")
-	Repository string `json:"repository" cborgen:"repository"` // Repository this layer belongs to
-	UserDID    string `json:"userDid" cborgen:"userDid"`       // DID of user who uploaded this layer
-	UserHandle string `json:"userHandle" cborgen:"userHandle"` // Handle of user (for display purposes)
-	CreatedAt  string `json:"createdAt" cborgen:"createdAt"`   // RFC3339 timestamp
+	Type      string `json:"$type" cborgen:"$type"`
+	Digest    string `json:"digest" cborgen:"digest"`       // Layer digest (e.g., "sha256:abc123...")
+	Size      int64  `json:"size" cborgen:"size"`           // Size in bytes
+	MediaType string `json:"mediaType" cborgen:"mediaType"` // Media type (e.g., "application/vnd.oci.image.layer.v1.tar+gzip")
+	Manifest  string `json:"manifest" cborgen:"manifest"`   // AT-URI of manifest that included this layer
+	UserDID   string `json:"userDid" cborgen:"userDid"`     // DID of user who uploaded this layer
+	CreatedAt string `json:"createdAt" cborgen:"createdAt"` // RFC3339 timestamp
 }
 
 // NewLayerRecord creates a new layer record
-func NewLayerRecord(digest string, size int64, mediaType, repository, userDID, userHandle string) *LayerRecord {
+// manifestURI: AT-URI of the manifest (e.g., "at://did:plc:xyz/io.atcr.manifest/abc123")
+func NewLayerRecord(digest string, size int64, mediaType, userDID, manifestURI string) *LayerRecord {
 	return &LayerRecord{
-		Type:       LayerCollection,
-		Digest:     digest,
-		Size:       size,
-		MediaType:  mediaType,
-		Repository: repository,
-		UserDID:    userDID,
-		UserHandle: userHandle,
-		CreatedAt:  time.Now().Format(time.RFC3339),
+		Type:      LayerCollection,
+		Digest:    digest,
+		Size:      size,
+		MediaType: mediaType,
+		Manifest:  manifestURI,
+		UserDID:   userDID,
+		CreatedAt: time.Now().Format(time.RFC3339),
 	}
 }
 

pkg/atproto/lexicon_test.go

···
 
 func TestNewLayerRecord(t *testing.T) {
 	tests := []struct {
-		name       string
-		digest     string
-		size       int64
-		mediaType  string
-		repository string
-		userDID    string
-		userHandle string
+		name        string
+		digest      string
+		size        int64
+		mediaType   string
+		userDID     string
+		manifestURI string
 	}{
 		{
-			name:       "standard layer",
-			digest:     "sha256:abc123",
-			size:       1024,
-			mediaType:  "application/vnd.oci.image.layer.v1.tar+gzip",
-			repository: "myapp",
-			userDID:    "did:plc:user123",
-			userHandle: "alice.bsky.social",
+			name:        "standard layer",
+			digest:      "sha256:abc123",
+			size:        1024,
+			mediaType:   "application/vnd.oci.image.layer.v1.tar+gzip",
+			userDID:     "did:plc:user123",
+			manifestURI: "at://did:plc:user123/io.atcr.manifest/abc123",
 		},
 		{
-			name:       "large layer",
-			digest:     "sha256:def456",
-			size:       1073741824, // 1GB
-			mediaType:  "application/vnd.oci.image.layer.v1.tar+gzip",
-			repository: "largeapp",
-			userDID:    "did:plc:user456",
-			userHandle: "bob.example.com",
+			name:        "large layer",
+			digest:      "sha256:def456",
+			size:        1073741824, // 1GB
+			mediaType:   "application/vnd.oci.image.layer.v1.tar+gzip",
+			userDID:     "did:plc:user456",
+			manifestURI: "at://did:plc:user456/io.atcr.manifest/def456",
 		},
 		{
-			name:       "empty values",
-			digest:     "",
-			size:       0,
-			mediaType:  "",
-			repository: "",
-			userDID:    "",
-			userHandle: "",
+			name:        "empty values",
+			digest:      "",
+			size:        0,
+			mediaType:   "",
+			userDID:     "",
+			manifestURI: "",
 		},
 		{
-			name:       "config layer",
-			digest:     "sha256:config123",
-			size:       512,
-			mediaType:  "application/vnd.oci.image.config.v1+json",
-			repository: "app/subapp",
-			userDID:    "did:web:example.com",
-			userHandle: "charlie.tangled.io",
+			name:        "config layer",
+			digest:      "sha256:config123",
+			size:        512,
+			mediaType:   "application/vnd.oci.image.config.v1+json",
+			userDID:     "did:web:example.com",
+			manifestURI: "at://did:web:example.com/io.atcr.manifest/config123",
 		},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			record := NewLayerRecord(tt.digest, tt.size, tt.mediaType, tt.repository, tt.userDID, tt.userHandle)
+			record := NewLayerRecord(tt.digest, tt.size, tt.mediaType, tt.userDID, tt.manifestURI)
 
 			// Verify all fields
 			if record == nil {
···
 				t.Errorf("MediaType = %q, want %q", record.MediaType, tt.mediaType)
 			}
 
-			if record.Repository != tt.repository {
-				t.Errorf("Repository = %q, want %q", record.Repository, tt.repository)
+			if record.Manifest != tt.manifestURI {
+				t.Errorf("Manifest = %q, want %q", record.Manifest, tt.manifestURI)
 			}
 
 			if record.UserDID != tt.userDID {
 				t.Errorf("UserDID = %q, want %q", record.UserDID, tt.userDID)
-			}
-
-			if record.UserHandle != tt.userHandle {
-				t.Errorf("UserHandle = %q, want %q", record.UserHandle, tt.userHandle)
 			}
 
 			// Verify CreatedAt is set and is a valid RFC3339 timestamp
···
 		"sha256:abc123",
 		1024,
 		"application/vnd.oci.image.layer.v1.tar+gzip",
-		"myapp",
 		"did:plc:user123",
-		"alice.bsky.social",
+		"at://did:plc:user123/io.atcr.manifest/abc123",
 	)
 
 	// Marshal to JSON
···
 	if decoded.MediaType != record.MediaType {
 		t.Errorf("MediaType = %q, want %q", decoded.MediaType, record.MediaType)
 	}
-	if decoded.Repository != record.Repository {
-		t.Errorf("Repository = %q, want %q", decoded.Repository, record.Repository)
+	if decoded.Manifest != record.Manifest {
+		t.Errorf("Manifest = %q, want %q", decoded.Manifest, record.Manifest)
 	}
 	if decoded.UserDID != record.UserDID {
 		t.Errorf("UserDID = %q, want %q", decoded.UserDID, record.UserDID)
-	}
-	if decoded.UserHandle != record.UserHandle {
-		t.Errorf("UserHandle = %q, want %q", decoded.UserHandle, record.UserHandle)
 	}
 	if decoded.CreatedAt != record.CreatedAt {
 		t.Errorf("CreatedAt = %q, want %q", decoded.CreatedAt, record.CreatedAt)

pkg/hold/oci/xrpc.go

···
 
 	// Parse request
 	var req struct {
-		Repository string `json:"repository"`
-		Tag        string `json:"tag"`
-		UserDID    string `json:"userDid"`
-		UserHandle string `json:"userHandle"`
-		Operation  string `json:"operation"` // "push" or "pull", defaults to "push" for backward compatibility
-		Manifest   struct {
+		Repository     string `json:"repository"`
+		Tag            string `json:"tag"`
+		UserDID        string `json:"userDid"`
+		ManifestDigest string `json:"manifestDigest"` // For building layer record AT-URIs
+		Operation      string `json:"operation"`      // "push" or "pull", defaults to "push" for backward compatibility
+		Manifest       struct {
 			MediaType string `json:"mediaType"`
 			Config    struct {
 				Digest string `json:"digest"`
···
 			postsEnabled = h.enableBlueskyPosts
 		}
 
+		// Build manifest AT-URI for layer records
+		manifestURI := atproto.BuildManifestURI(req.UserDID, req.ManifestDigest)
+
 		// Create layer records for each blob
 		for _, layer := range req.Manifest.Layers {
 			record := atproto.NewLayerRecord(
 				layer.Digest,
 				layer.Size,
 				layer.MediaType,
-				req.Repository,
 				req.UserDID,
-				req.UserHandle,
+				manifestURI,
 			)
 
 			_, _, err := h.pds.CreateLayerRecord(ctx, record)
···
 
 		// Create Bluesky post if enabled
 		if postsEnabled {
+			// Resolve handle from DID (cached, 24-hour TTL)
+			_, userHandle, _, resolveErr := atproto.ResolveIdentity(ctx, req.UserDID)
+			if resolveErr != nil {
+				slog.Warn("Failed to resolve handle for user", "did", req.UserDID, "error", resolveErr)
+				userHandle = req.UserDID // Fallback to DID if resolution fails
+			}
+
 			// Extract manifest digest from first layer (or use config digest as fallback)
 			manifestDigest := req.Manifest.Config.Digest
 			if len(req.Manifest.Layers) > 0 {
···
 				h.driver,
 				req.Repository,
 				req.Tag,
-				req.UserHandle,
+				userHandle,
 				req.UserDID,
 				manifestDigest,
 				totalSize,

pkg/hold/pds/layer.go

···
 	"fmt"
 
 	"atcr.io/pkg/atproto"
+	lexutil "github.com/bluesky-social/indigo/lex/util"
+	"github.com/bluesky-social/indigo/repo"
 )
 
 // CreateLayerRecord creates a new layer record in the hold's PDS
···
 	// not for runtime queries
 	return nil, "", fmt.Errorf("ListLayerRecords not yet implemented")
 }
+
+// QuotaStats represents storage quota information for a user
+type QuotaStats struct {
+	UserDID     string `json:"userDid"`
+	UniqueBlobs int    `json:"uniqueBlobs"`
+	TotalSize   int64  `json:"totalSize"`
+}
+
+// GetQuotaForUser calculates storage quota for a specific user
+// It iterates through all layer records, filters by userDid, deduplicates by digest,
+// and sums the sizes of unique blobs.
+func (p *HoldPDS) GetQuotaForUser(ctx context.Context, userDID string) (*QuotaStats, error) {
+	if p.recordsIndex == nil {
+		return nil, fmt.Errorf("records index not available")
+	}
+
+	// Get session for reading record data
+	session, err := p.carstore.ReadOnlySession(p.uid)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create session: %w", err)
+	}
+
+	head, err := p.carstore.GetUserRepoHead(ctx, p.uid)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get repo head: %w", err)
+	}
+
+	if !head.Defined() {
+		// Empty repo - return zero stats
+		return &QuotaStats{UserDID: userDID}, nil
+	}
+
+	repoHandle, err := repo.OpenRepo(ctx, session, head)
+	if err != nil {
+		return nil, fmt.Errorf("failed to open repo: %w", err)
+	}
+
+	// Track unique digests and their sizes
+	digestSizes := make(map[string]int64)
+
+	// Iterate all layer records via the index
+	cursor := ""
+	batchSize := 1000 // Process in batches
+
+	for {
+		records, nextCursor, err := p.recordsIndex.ListRecords(atproto.LayerCollection, batchSize, cursor, true)
+		if err != nil {
+			return nil, fmt.Errorf("failed to list layer records: %w", err)
+		}
+
+		for _, rec := range records {
+			// Construct record path and get the record data
+			recordPath := rec.Collection + "/" + rec.Rkey
+
+			_, recBytes, err := repoHandle.GetRecordBytes(ctx, recordPath)
+			if err != nil {
+				// Skip records we can't read
+				continue
+			}
+
+			// Decode the layer record
+			recordValue, err := lexutil.CborDecodeValue(*recBytes)
+			if err != nil {
+				continue
+			}
+
+			layerRecord, ok := recordValue.(*atproto.LayerRecord)
+			if !ok {
+				continue
+			}
+
+			// Filter by userDID
+			if layerRecord.UserDID != userDID {
+				continue
+			}
+
+			// Deduplicate by digest - keep the size (could be different pushes of same blob)
+			// Store the size - we only count each unique digest once
+			if _, exists := digestSizes[layerRecord.Digest]; !exists {
+				digestSizes[layerRecord.Digest] = layerRecord.Size
+			}
+		}
+
+		if nextCursor == "" {
+			break
+		}
+		cursor = nextCursor
+	}
+
+	// Calculate totals
+	var totalSize int64
+	for _, size := range digestSizes {
+		totalSize += size
+	}
+
+	return &QuotaStats{
+		UserDID:     userDID,
+		UniqueBlobs: len(digestSizes),
+		TotalSize:   totalSize,
+	}, nil
+}

pkg/hold/pds/layer_test.go

···
 				"sha256:abc123def456",
 				1048576, // 1 MB
 				"application/vnd.oci.image.layer.v1.tar+gzip",
-				"myapp",
 				"did:plc:alice123",
-				"alice.bsky.social",
+				"at://did:plc:alice123/io.atcr.manifest/abc123def456",
 			),
 			wantErr: false,
 		},
···
 				"sha256:fedcba987654",
 				1073741824, // 1 GB
 				"application/vnd.docker.image.rootfs.diff.tar.gzip",
-				"debian",
 				"did:plc:bob456",
-				"bob.example.com",
+				"at://did:plc:bob456/io.atcr.manifest/fedcba987654",
 			),
 			wantErr: false,
 		},
 		{
 			name: "invalid record type",
 			record: &atproto.LayerRecord{
-				Type:       "wrong.type",
-				Digest:     "sha256:abc123",
-				Size:       1024,
-				MediaType:  "application/vnd.oci.image.layer.v1.tar",
-				Repository: "test",
-				UserDID:    "did:plc:test",
-				UserHandle: "test.example.com",
+				Type:      "wrong.type",
+				Digest:    "sha256:abc123",
+				Size:      1024,
+				MediaType: "application/vnd.oci.image.layer.v1.tar",
+				Manifest:  "at://did:plc:test/io.atcr.manifest/abc123",
+				UserDID:   "did:plc:test",
 			},
 			wantErr:   true,
 			errSubstr: "invalid record type",
···
 		{
 			name: "missing digest",
 			record: &atproto.LayerRecord{
-				Type:       atproto.LayerCollection,
-				Digest:     "",
-				Size:       1024,
-				MediaType:  "application/vnd.oci.image.layer.v1.tar",
-				Repository: "test",
-				UserDID:    "did:plc:test",
-				UserHandle: "test.example.com",
+				Type:      atproto.LayerCollection,
+				Digest:    "",
+				Size:      1024,
+				MediaType: "application/vnd.oci.image.layer.v1.tar",
+				Manifest:  "at://did:plc:test/io.atcr.manifest/abc123",
+				UserDID:   "did:plc:test",
 			},
 			wantErr:   true,
 			errSubstr: "digest is required",
···
 		{
 			name: "zero size",
 			record: &atproto.LayerRecord{
-				Type:       atproto.LayerCollection,
-				Digest:     "sha256:abc123",
-				Size:       0,
-				MediaType:  "application/vnd.oci.image.layer.v1.tar",
-				Repository: "test",
-				UserDID:    "did:plc:test",
-				UserHandle: "test.example.com",
+				Type:      atproto.LayerCollection,
+				Digest:    "sha256:abc123",
+				Size:      0,
+				MediaType: "application/vnd.oci.image.layer.v1.tar",
+				Manifest:  "at://did:plc:test/io.atcr.manifest/abc123",
+				UserDID:   "did:plc:test",
 			},
 			wantErr:   true,
 			errSubstr: "size must be positive",
···
 		{
 			name: "negative size",
 			record: &atproto.LayerRecord{
-				Type:       atproto.LayerCollection,
-				Digest:     "sha256:abc123",
-				Size:       -1,
-				MediaType:  "application/vnd.oci.image.layer.v1.tar",
-				Repository: "test",
-				UserDID:    "did:plc:test",
-				UserHandle: "test.example.com",
+				Type:      atproto.LayerCollection,
+				Digest:    "sha256:abc123",
+				Size:      -1,
+				MediaType: "application/vnd.oci.image.layer.v1.tar",
+				Manifest:  "at://did:plc:test/io.atcr.manifest/abc123",
+				UserDID:   "did:plc:test",
 			},
 			wantErr:   true,
 			errSubstr: "size must be positive",
···
 func TestCreateLayerRecord_MultipleRecords(t *testing.T) {
 	// Test creating multiple layer records for the same manifest
 	pds, ctx := setupTestPDS(t)
+
+	manifestURI := "at://did:plc:test123/io.atcr.manifest/manifestabc123"
 
 	layers := []struct {
 		digest string
···
 			layer.digest,
 			layer.size,
 			"application/vnd.oci.image.layer.v1.tar+gzip",
-			"multi-layer-app",
 			"did:plc:test123",
-			"test.example.com",
+			manifestURI,
 		)
 
 		rkey, cid, err := pds.CreateLayerRecord(ctx, record)
···
 	digest := "sha256:abc123def456"
 	size := int64(1048576)
 	mediaType := "application/vnd.oci.image.layer.v1.tar+gzip"
-	repository := "myapp"
 	userDID := "did:plc:alice123"
-	userHandle := "alice.bsky.social"
+	manifestURI := "at://did:plc:alice123/io.atcr.manifest/abc123def456"
 
-	record := atproto.NewLayerRecord(digest, size, mediaType, repository, userDID, userHandle)
+	record := atproto.NewLayerRecord(digest, size, mediaType, userDID, manifestURI)
 
 	if record == nil {
 		t.Fatal("NewLayerRecord() returned nil")
···
 		t.Errorf("MediaType = %q, want %q", record.MediaType, mediaType)
 	}
 
-	if record.Repository != repository {
-		t.Errorf("Repository = %q, want %q", record.Repository, repository)
+	if record.Manifest != manifestURI {
+		t.Errorf("Manifest = %q, want %q", record.Manifest, manifestURI)
 	}
 
 	if record.UserDID != userDID {
 		t.Errorf("UserDID = %q, want %q", record.UserDID, userDID)
-	}
-
-	if record.UserHandle != userHandle {
-		t.Errorf("UserHandle = %q, want %q", record.UserHandle, userHandle)
 	}
 
 	if record.CreatedAt == "" {
···
 func TestLayerRecord_FieldValidation(t *testing.T) {
 	// Test various field values
 	tests := []struct {
-		name       string
-		digest     string
-		size       int64
-		mediaType  string
-		repository string
-		userDID    string
-		userHandle string
+		name        string
+		digest      string
+		size        int64
+		mediaType   string
+		userDID     string
+		manifestURI string
 	}{
 		{
-			name:       "typical OCI layer",
-			digest:     "sha256:e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f",
-			size:       12582912, // 12 MB
-			mediaType:  "application/vnd.oci.image.layer.v1.tar+gzip",
-			repository: "hsm-secrets-operator",
-			userDID:    "did:plc:evan123",
-			userHandle: "evan.jarrett.net",
+			name:        "typical OCI layer",
+			digest:      "sha256:e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f",
+			size:        12582912, // 12 MB
+			mediaType:   "application/vnd.oci.image.layer.v1.tar+gzip",
+			userDID:     "did:plc:evan123",
+			manifestURI: "at://did:plc:evan123/io.atcr.manifest/abc123",
 		},
 		{
-			name:       "Docker layer format",
-			digest:     "sha256:abc123",
-			size:       1024,
-			mediaType:  "application/vnd.docker.image.rootfs.diff.tar.gzip",
-			repository: "nginx",
-			userDID:    "did:plc:user456",
-			userHandle: "user.example.com",
+			name:        "Docker layer format",
+			digest:      "sha256:abc123",
+			size:        1024,
+			mediaType:   "application/vnd.docker.image.rootfs.diff.tar.gzip",
+			userDID:     "did:plc:user456",
+			manifestURI: "at://did:plc:user456/io.atcr.manifest/def456",
 		},
 		{
-			name:       "uncompressed layer",
-			digest:     "sha256:def456",
-			size:       2048,
-			mediaType:  "application/vnd.oci.image.layer.v1.tar",
-			repository: "alpine",
-			userDID:    "did:plc:user789",
-			userHandle: "user.bsky.social",
+			name:        "uncompressed layer",
+			digest:      "sha256:def456",
+			size:        2048,
+			mediaType:   "application/vnd.oci.image.layer.v1.tar",
+			userDID:     "did:plc:user789",
+			manifestURI: "at://did:plc:user789/io.atcr.manifest/ghi789",
 		},
 	}
 
···
 				tt.digest,
 				tt.size,
 				tt.mediaType,
-				tt.repository,
 				tt.userDID,
-				tt.userHandle,
+				tt.manifestURI,
 			)
 
 			if record == nil {
···
 
 			if record.Digest != tt.digest {
 				t.Errorf("Digest = %q, want %q", record.Digest, tt.digest)
+			}
+
+			if record.Manifest != tt.manifestURI {
+				t.Errorf("Manifest = %q, want %q", record.Manifest, tt.manifestURI)
 			}
 		})
 	}

pkg/hold/pds/xrpc.go

···
 		r.Use(h.requireAuth)
 		r.Post(atproto.HoldRequestCrew, h.HandleRequestCrew)
 	})
+
+	// Public quota endpoint (no auth - quota is per-user, just needs userDid param)
+	r.Get(atproto.HoldGetQuota, h.HandleGetQuota)
 }
 
 // HandleHealth returns health check information
···
 	// Clients should use multipart upload flow via com.atproto.repo.uploadBlob
 	return ""
 }
+
+// HandleGetQuota returns storage quota information for a user
+// This calculates the total unique blob storage used by a specific user
+// by iterating layer records and deduplicating by digest.
+func (h *XRPCHandler) HandleGetQuota(w http.ResponseWriter, r *http.Request) {
+	userDID := r.URL.Query().Get("userDid")
+	if userDID == "" {
+		http.Error(w, "missing required parameter: userDid", http.StatusBadRequest)
+		return
+	}
+
+	// Validate DID format
+	if !atproto.IsDID(userDID) {
+		http.Error(w, "invalid userDid format", http.StatusBadRequest)
+		return
+	}
+
+	// Get quota stats
+	stats, err := h.pds.GetQuotaForUser(r.Context(), userDID)
+	if err != nil {
+		slog.Error("Failed to get quota", "userDid", userDID, "error", err)
+		http.Error(w, fmt.Sprintf("failed to get quota: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(stats)
+}