# Storage Write Queue Observer Architecture & Inverted Dependency Governance

## Overview

This architecture document defines the governance rules for decoupled event dispatching and dependency inversion within the Content-Addressable Storage (CAS) write queue subsystem (`pkg/storage/cas`).

## Background & Problem Statement

Prior to this specification, `ListingIndexWriteQueue` relied on global atomic function pointers (`globalListingIndexBatchEventCallback`, `SetListingIndexBatchEventCallback`) to communicate batch lifecycle events across packages. The presentation layer (`cmd/zqk/system`) mutated these global variables at startup to bind coordinator event emission.

This pattern violated core architectural layering invariants:
1. **Presentation Layer Contamination**: Presentation components mutated low-level storage internal hooks.
2. **Multi-Instance Interference**: Concurrent test cases or isolated storage instances shared the same mutable global pointer, causing event leakage and test race conditions.
3. **Inverted Dependency Injection**: Hook mutation bypassed compile-time interface contracts.

## Architectural Solution: Observer Pattern

The storage write queue subsystem implements the Observer pattern at the instance level:

```
┌─────────────────────────────────┐
│     ListingIndexWriteQueue      │
│  (Manages per-kind write queues)│
└────────────────┬────────────────┘
                 │
                 ▼ RegisterBatchEventListener(listener)
┌──────────────────────────────────────────────────┐
│         ListingIndexBatchEventListener           │
│                    <<interface>>                 │
│  + OnListingIndexBatchEvent(...)                 │
└──────────────────────────────────────────────────┘
                 ▲
                 │ implements
┌────────────────┴──────────────────┐
│   Coordinator/Logging Observers   │
│   (e.g. ListingIndexBatchEventFunc)
└───────────────────────────────────┘
```

### Invariants

1. **Instance-Scoped Listeners**: `ListingIndexWriteQueue` maintains an internal slice of registered listeners protected by a read-write mutex.
2. **Zero Global Mutation**: Presentation and coordinator layers wire observers onto the queue instance directly rather than mutating package-level function pointers.
3. **Concurrency Safety**: Workers dispatch events asynchronously to instance-registered listeners without holding internal queue locks, ensuring non-blocking event flow and zero cross-queue leakage.