# Sovereign Transformers: Beyond the SQL Noise

> "Code is not just logic; it is a contract of truth. When infrastructure leaks into your application layer, the truth becomes noisy."

## 1. The Mess (The Diagnostic)

In the early stages of our **BOS Era v2.0** migration, we faced a classic engineering sin: the **God-Service**. Our `RadarSnapshotService` was "functional" but architecturally loud. 

It was directly injecting `PDO`, executing raw SQL queries, and handling UI formatting—all in a single file. 

```php
// The Original Mess (Contexts/Hub/Application/RadarSnapshotService.php)
public function getSnapshot(string $merchantId): array {
    $stmt = $this->pdo->prepare("SELECT SUM(total_amount) FROM finance_sales_tickets WHERE...");
    // ... raw query noise ...
    $liveRevenue = (float) $stmt->fetchColumn();
    
    return [
        'business_pulse' => [
            'live_revenue' => $liveRevenue,
            'occupancy_rate' => round(($confirmed / ($active * 8)) * 100) . '%', // UI Logic leaking!
        ]
    ];
}
```

### Why this was Debt:
*   **Infrastructure Leaking:** The service knew too much about table names and SQL syntax.
*   **Data Leaking:** Returning raw associative arrays from PDO is a security vulnerability (Anti-Leaking failure).
*   **Location Blindness:** Formatting dates without considering the Merchant's local offset (emitting UTC 'Z' by default).

---

## 2. The Strategy (The Vision)

We defined **ADR-006**, establishing a strict separation of concerns through two specialized components:

1.  **The DataProvider:** A silent infrastructure agent. Its only job is to fetch raw data. No logic, no formatting. Just the raw pulse of the database.
2.  **The Sovereign Transformer:** A strict customs officer. It acts as a mandatory whitelist, ensuring only authorized fields leave the API, and enforcing **Location Awareness** (RFC3339 with dynamic offsets).

The Service then becomes a **Pure Orchestrator**. It asks for data, passes it through the transformer, and delivers the result.

---

## 3. The Craft (The Transformation)

Following our **TDD Protocol**, we first secured the "Green State" with an integration test suite. Then, we performed the surgery.

### The New Infrastructure Layer
We abstracted the SQL into a dedicated `RadarDataProvider`.

```php
class RadarDataProvider {
    public function getLiveRevenue(string $merchantId, string $start, string $end): float {
        // SQL stays here, hidden from the application logic.
    }
}
```

### The Sovereign Contract
We implemented the `RadarSnapshotTransformer`, inheriting from our `BaseTransformer`. This guarantees that every date emitted follows the Merchant's local time, not a generic UTC string.

```php
class RadarSnapshotTransformer extends BaseTransformer {
    public function transform(array $data): array {
        return [
            'business_pulse' => [
                'live_revenue' => (float) $data['live_revenue'],
                'occupancy_rate' => $this->calculateOccupancy($data),
                // Location Awareness enforced here
            ]
        ];
    }
}
```

---

## 4. The Result (The Art)

The result is a service that reads like a story, not a database dump.

```php
// The Refactored Orchestrator
public function getSnapshot(string $merchantId): array {
    $timezone = $this->dataProvider->getMerchantTimezone($merchantId);
    [$start, $end] = $this->getTodayRange($timezone);

    $data = [
        'live_revenue' => $this->dataProvider->getLiveRevenue($merchantId, $start, $end),
        // ... orchestration logic ...
    ];

    return $this->radarTransformer->transform($data);
}
```

### The Evidence:
- **0 Lines of SQL** in the application service.
- **Strict Whitelisting** (Safe from Data Leaking).
- **100% Location Awareness** (Dynamic RFC3339 offsets).
- **17 Assertions Passing** in our integration suite.

This is not just refactoring; it's **Engineering Sovereignty**.

---
**dammgo labs** - _Engineering as Art._