NovaShell

✏️ Edit: MIGRATION_RUNBOOK.md

# MIGRATION RUNBOOK: Laravel SMS → Microservices

**FROM:** Laravel Monolith  
**TO:** Go Messaging Service (phase 1), Spring Boot/Kotlin Dashboard (later phase)  
**STRATEGY:** Strangler Pattern with Feature Flags (Incremental, Tenant-Level Rollout)

---

# PHASE A: SYSTEM BASELINE (SOURCE OF TRUTH)

## 0. HARD EXECUTION INVARIANTS (NON-NEGOTIABLE)

These invariants MUST be enforced at all times during migration.

### Invariant 1 — Single Execution Authority

At any moment, for a given `message_uuid`, exactly ONE system may perform the external provider send.

**Mode Behavior (Enforced):**

| Mode   | Laravel Send | Go Send        | Go dry_run | Quota Decrement | Fallback Allowed |
|--------|--------------|----------------|------------|-----------------|------------------|
| OFF    | YES          | NO             | N/A        | YES (legacy)    | NO               |
| SHADOW | YES          | YES (dry_run)  | true       | NO              | NO               |
| ON     | NO*          | YES            | false      | YES             | YES*             |

*ON mode: Laravel fallback is allowed ONLY when Go request:
- times out (>500ms), OR
- returns transport failure, OR
- circuit breaker is OPEN

### Invariant 2 — UUID Generated ONCE at Entry Point

`$messageUuidMap` MUST be generated BEFORE any send logic executes.

UUID generation MUST NOT occur:
- Inside retry loops
- Inside provider loops
- Inside fallback paths

**Canonical Pattern:**
```php
$messageUuidMap = [];
foreach ($campaignSMSs as $sms) {
    $messageUuidMap[$sms->id] = (string) \Str::uuid();
}
// All subsequent logic uses $messageUuidMap[$sms->id]
```

### Invariant 3 — Laravel is the ONLY Writer to sms_logs

Go service MUST NOT write to `sms_logs`.

Go writes ONLY to its internal `go_sms_logs` table.

Laravel writes Go results into `sms_logs` with:
- `source = 'go'`
- `message_uuid`
- `provider_message_id`
- `status`

### Invariant 4 — Quota Decrement Safety

Quota decrement MUST occur ONLY when:
- `mode == ON`
- AND `status IN ('accepted', 'duplicate')`

Quota MUST NOT decrement in SHADOW mode.

## 1. Evidence Summary (Repo-Backed)

**Entry Point (SMS Campaign Send):**  
- `app/Http/Controllers/SmsController.php::campaignSendSms` (method definition).  
Evidence: `app/Http/Controllers/SmsController.php` (search `public function campaignSendSms`).

**Tenant Resolution (Legacy):**  
- `app/Models/Sms.php::scopeHasAgent` uses `agent_owner_id()` for Agents, otherwise `Auth::user()->id`.  
Evidence: `app/Models/Sms.php::scopeHasAgent`, `app/Helpers.php::agent_owner_id`.

**Agent Owner Logic:**  
- `app/Helpers.php::agent_owner_id` returns `Agent::where('user_id', Auth::id())->first()->assined_for_customer_id`.  
Evidence: `app/Helpers.php::agent_owner_id`.

**Legacy Logging (smsLog):**  
- `app/Helpers.php::smsLog` writes to `SmsLog` with `user_id`, `campaign_id`, `number`, `message_id`, `message`, `gateway`.  
Evidence: `app/Helpers.php::smsLog`.

**Legacy Billing / Quota Decrement (SMS):**  
- `EmailSMSLimitRate::where('owner_id', Auth::id())->decrement('sms', count(...))` appears in `campaignSendSms`.  
Evidence: `app/Http/Controllers/SmsController.php` (search `EmailSMSLimitRate::where('owner_id', Auth::id())`).

**Providers Configured in Laravel UI & Send Logic (SMS):**  
- Providers include: `twilio`, `nexmo`, `textlocal`, `plivo`, `signalwire`, `infobip`, `viber`, `whatsapp`, `telesign`, `sinch`, `clickatell`, `mailjet`, `lao`, `aakash`.  
Evidence: `app/Http/Controllers/SmsController.php` switch cases containing these provider names.

**sms_logs Schema (Current):**  
- `user_id`, `campaign_id`, `number`, `message_id`, `message`, `gateway`, timestamps.  
Evidence: `database/migrations/2020_12_10_131409_create_sms_logs_table.php`.

**sms & sms_services Schemas (Credentials Storage):**  
- Tables contain `sms_name`, `sms_id`, `sms_token`, `sms_from`, `sms_number`, `url`, `owner_id`.  
Evidence: `database/migrations/2020_12_09_121240_create_sms_table.php`, `database/migrations/2022_04_28_131810_create_sms_services_table.php`.

**Session Driver Default:**  
- `SESSION_DRIVER` defaults to `file`.  
Evidence: `config/session.php` (`'driver' => env('SESSION_DRIVER', 'file')`).

**UNCONFIRMED (Requires Evidence):**  
- Spring Boot/Kotlin Dashboard repo location, routes, or auth integration are not present in this repository.  
Required evidence: repo URL or local path + controller/route definitions.

**UNCONFIRMED (Requires Evidence):**  
- Direct PHP<->Java session deserialization feasibility.  
Required evidence: storage format and serialization proof across stacks.

## 2. Canonical Contract (Defined Once; Referenced Everywhere)

**Endpoint:** `POST /internal/v1/sms/send-batch`  
**Request:**
```json
{"tenant_id":123,"campaign_id":456,"messages":[{"message_uuid":"uuid","recipient":"+1234567890","body":"text","provider":"twilio"}],"dry_run":false}
```
**Response:**
```json
{"batch_id":"uuid","total":1,"accepted":1,"rejected":0,"results":[{"message_uuid":"uuid","status":"accepted","provider_message_id":"SM123","error_code":null,"error_message":null}]}
```
**Auth:** `X-Internal-API-Key` header

## 3. Canonical Tenant Resolution (REQUIRED)

**Function to add:** `resolveTenantId()`  
```php
function resolveTenantId(): int {
    if (!Auth::check()) {
        if (App::runningInConsole()) {
            $systemUserId = (int) config('app.system_user_id', 0);
            if ($systemUserId > 0) {
                return $systemUserId;
            }
            throw new RuntimeException('system_user_id not configured for console context');
        }
        throw new RuntimeException('Unauthenticated context: resolveTenantId requires Auth::check()');
    }
    if (Auth::user()->user_type === 'Agent') {
        $ownerId = agent_owner_id();
        if (!$ownerId) {
            throw new RuntimeException('Agent owner id not found for authenticated Agent');
        }
        return $ownerId;
    }
    return Auth::id();
}
```

**Rule:** Replace all tenant-context `Auth::id()` lookups with `resolveTenantId()` for:  
- Feature flags  
- Quota decrement  
- Go service credentials loading  
- Internal API calls

---

# PHASE B: ATOMIC MIGRATION STEPS (Step 1..Step N)

## Step 1: Install Doctrine DBAL (Prerequisite)

### 1. Purpose & Pre-requisites
Enable `change()` operations in Laravel migrations.

### 2. Files Involved
- `composer.json`
- `composer.lock`

### 3. Commands to Run
```bash
composer require doctrine/dbal
```

### 4. Precise Code Changes
Composer dependency only.

### 5. Verification Gate
```bash
composer show doctrine/dbal
```
**STOP if FAIL. Execute rollback only.**

### 6. Rollback Path
```bash
composer remove doctrine/dbal
```

### 7. Artifacts Created/Changed
- `composer.json`
- `composer.lock`

### 8. Git Commit
```bash
git add composer.json composer.lock
git commit -m "chore: add doctrine/dbal prerequisite (Step 1)"
```

### 9. Agent Prompt (Copy/Paste)
```
Execute Step 1 only: Install doctrine/dbal, verify it appears in composer show, commit if PASS.
```

---

## Step 2: Add Tracing Columns to sms_logs

### 1. Purpose & Pre-requisites
Add minimal tracing fields and `source` to `sms_logs`.

### 2. Files Involved
- `database/migrations/*_add_tracing_to_sms_logs.php`

### 3. Commands to Run
```bash
php artisan make:migration add_tracing_to_sms_logs
```

### 4. Precise Code Changes
```php
Schema::table('sms_logs', function (Blueprint $table) {
    $table->char('message_uuid', 36)->nullable()->after('message_id');
    $table->unsignedBigInteger('tenant_id')->nullable()->after('user_id');
    $table->string('provider', 50)->nullable()->after('gateway');
    $table->boolean('dry_run')->default(false)->after('provider');
    $table->string('status', 20)->nullable()->after('dry_run');
    $table->string('provider_message_id', 191)->nullable()->after('status');
    $table->string('error_code', 50)->nullable()->after('provider_message_id');
    $table->string('source', 20)->default('laravel')->after('error_code');

$table->index('message_uuid');
    $table->index('tenant_id');
    $table->index('source');
    $table->index('provider');
    $table->index(['source', 'created_at']);
});
```

### 5. Verification Gate
```bash
php artisan migrate
php artisan tinker --execute="
echo Schema::hasColumn('sms_logs','message_uuid') ? 'PASS' : 'FAIL';
"
php artisan tinker --execute="
\$driver = DB::getDriverName();
if (\$driver === 'mysql') {
  \$rows = DB::select(\"SELECT INDEX_NAME FROM information_schema.statistics WHERE table_schema = DATABASE() AND table_name = 'sms_logs' AND index_name = 'sms_logs_source_created_at_index'\");
} elseif (\$driver === 'pgsql') {
  \$rows = DB::select(\"SELECT indexname FROM pg_indexes WHERE tablename = 'sms_logs' AND indexname = 'sms_logs_source_created_at_index'\");
} else {
  \$rows = [];
}
echo count(\$rows) > 0 ? 'PASS' : 'FAIL';
"
php artisan tinker --execute="
\$driver = DB::getDriverName();
if (\$driver === 'mysql') {
  \$rows = DB::select(\"SELECT INDEX_NAME FROM information_schema.statistics WHERE table_schema = DATABASE() AND table_name = 'sms_logs' AND index_name = 'sms_logs_provider_index'\");
} elseif (\$driver === 'pgsql') {
  \$rows = DB::select(\"SELECT indexname FROM pg_indexes WHERE tablename = 'sms_logs' AND indexname = 'sms_logs_provider_index'\");
} else {
  \$rows = [];
}
echo count(\$rows) > 0 ? 'PASS' : 'FAIL';
"
```
**STOP if FAIL. Execute rollback only.**

### 6. Rollback Path
```bash
php artisan migrate:rollback --step=1
```

### 7. Artifacts Created/Changed
- `database/migrations/*_add_tracing_to_sms_logs.php`

### 8. Git Commit
```bash
git add database/migrations/*add_tracing_to_sms_logs*
git commit -m "feat: add tracing fields to sms_logs (Step 2)"
```

### 9. Agent Prompt (Copy/Paste)
```
Execute Step 2: Add tracing fields migration for sms_logs. Run migrate, verify PASS, commit if PASS.
```

---

## Step 3: Add Canonical Tenant Resolver + Extend smsLog Signature

### 1. Purpose & Pre-requisites
Add `resolveTenantId()` and extend `smsLog()` to support tracing fields and source.

### 2. Files Involved
- `app/Helpers.php`

### 3. Commands to Run
```bash
cd .
```

### 4. Precise Code Changes

**Add after `agent_owner_id()` in `app/Helpers.php`:**
```php
/**
 * Resolve tenant ID (canonical for migration)
 */
function resolveTenantId(): int
{
    if (!Auth::check()) {
        if (App::runningInConsole()) {
            $systemUserId = (int) config('app.system_user_id', 0);
            if ($systemUserId > 0) {
                return $systemUserId;
            }
            throw new RuntimeException('system_user_id not configured for console context');
        }
        throw new RuntimeException('Unauthenticated context: resolveTenantId requires Auth::check()');
    }
    if (Auth::user()->user_type === 'Agent') {
        $ownerId = agent_owner_id();
        if (!$ownerId) {
            throw new RuntimeException('Agent owner id not found for authenticated Agent');
        }
        return $ownerId;
    }
    return Auth::id();
}
```

**Replace `smsLog()` in `app/Helpers.php`:**
```php
function smsLog(
    $campaign_id,
    $number,
    $message,
    $gateway,
    $message_uuid = null,
    $source = 'laravel',
    $tenant_id = null,
    $provider = null,
    $dry_run = false,
    $status = null,
    $provider_message_id = null,
    $error_code = null
) {
    $smsLog = new SmsLog();
    $smsLog->user_id = Auth::user()->id;
    $smsLog->campaign_id = $campaign_id;
    $smsLog->number = $number;
    $smsLog->message_id = Str::random(20);
    $smsLog->message_uuid = $message_uuid ?? (string) Str::uuid();
    $smsLog->message = $message;
    $smsLog->gateway = $gateway;
    $smsLog->source = $source;
    $smsLog->tenant_id = $tenant_id ?? resolveTenantId();
    $smsLog->provider = $provider ?? $gateway;
    $smsLog->dry_run = $dry_run ? 1 : 0;
    $smsLog->status = $status;
    $smsLog->provider_message_id = $provider_message_id;
    $smsLog->error_code = $error_code;
    $smsLog->save();

return $smsLog;
}
```

**Usage Rules (Mandatory):**
- Laravel is the single writer to `sms_logs`.
- `ON` mode must call `smsLog(..., $source='go')`.
- `SHADOW` and `OFF` must use default `source='laravel'`.
- Go service must never write to `sms_logs`.

### 5. Verification Gate
```bash
php artisan tinker --execute="
\$log = smsLog(null, '+1234567890', 'Test', 'test');
if (empty(\$log->message_uuid)) exit(1);
echo 'PASS';
"
# Console path should return system_user_id
php artisan tinker --execute="echo resolveTenantId() === (int) config('app.system_user_id', 0) ? 'PASS' : 'FAIL';"
# Web unauthenticated should throw RuntimeException (simulate by clearing auth in a web request)
```
**STOP if FAIL. Execute rollback only.**

### 6. Rollback Path
```bash
git checkout HEAD -- app/Helpers.php
```

### 7. Artifacts Created/Changed
- `app/Helpers.php`

### 8. Git Commit
```bash
git add app/Helpers.php
git commit -m "feat: add resolveTenantId + extend smsLog (Step 3)"
```

### 9. Agent Prompt (Copy/Paste)
```
Execute Step 3: Add resolveTenantId() and extend smsLog(). Verify tinker PASS, commit if PASS.
```

---

## Step 4: Backfill sms_logs Tracing Fields

### 1. Purpose & Pre-requisites
Backfill `message_uuid`, `tenant_id`, and `source` for existing rows.

### 2. Files Involved
- `app/Console/Commands/BackfillSmsLogTracing.php`

### 3. Commands to Run
```bash
php artisan make:command BackfillSmsLogTracing
```

### 4. Precise Code Changes
```php
<?php
namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Str;

class BackfillSmsLogTracing extends Command
{
    protected $signature = 'sms:backfill-tracing {--batch=1000}';
    protected $description = 'Backfill sms_logs tracing fields';

public function handle()
    {
        $batch = (int) $this->option('batch');

$startedAt = now();
        $this->info('BACKFILL_STARTED_AT=' . $startedAt->toDateTimeString());

DB::table('sms_logs')
            ->whereNull('message_uuid')
            ->orderBy('id')
            ->chunkById($batch, function ($rows) use ($startedAt) {
                $batchStart = microtime(true);
                DB::transaction(function () use ($rows) {
                    foreach ($rows as $row) {
                        DB::table('sms_logs')->where('id', $row->id)->update([
                            'message_uuid' => (string) Str::uuid(),
                            'source' => 'laravel',
                            'updated_at' => now(),
                        ]);
                    }
                });
                $elapsedMs = (int) ((microtime(true) - $batchStart) * 1000);
                $lastProcessedId = $rows->last()->id ?? null;
                Log::info('sms:backfill-tracing uuid batch', [
                    'count' => count($rows),
                    'min_id' => $rows->first()->id ?? null,
                    'max_id' => $lastProcessedId,
                    'lastProcessedId' => $lastProcessedId,
                    'elapsed_ms' => $elapsedMs
                ]);
                usleep(50000);
            }, 'id');

// tenant_id backfill from users/agents
        $minId = DB::table('sms_logs')->min('id');
        $maxId = DB::table('sms_logs')->max('id');
        if ($minId && $maxId) {
            for ($start = $minId; $start <= $maxId; $start += $batch) {
                $end = $start + $batch - 1;
                $batchStart = microtime(true);
                $processed = DB::affectingStatement("
                    UPDATE sms_logs l
                    SET tenant_id = CASE
                        WHEN (SELECT u.user_type FROM users u WHERE u.id = l.user_id) = 'Agent'
                        THEN (SELECT a.assined_for_customer_id FROM agents a WHERE a.user_id = l.user_id)
                        ELSE l.user_id
                    END
                    WHERE l.tenant_id IS NULL AND l.id BETWEEN ? AND ?
                ", [$start, $end]);
                $elapsedMs = (int) ((microtime(true) - $batchStart) * 1000);
                Log::info('sms:backfill-tracing tenant_id batch', [
                    'range' => [$start, $end],
                    'processed' => $processed,
                    'lastProcessedId' => $end,
                    'elapsed_ms' => $elapsedMs
                ]);
                usleep(50000);
            }
        }
        $remaining = DB::table('sms_logs')->whereNull('message_uuid')->count();
        $this->info($remaining === 0 ? 'PASS' : "FAIL: {$remaining} NULL");
        return $remaining === 0 ? 0 : 1;
    }
}
```

### 5. Verification Gate
```bash
php artisan sms:backfill-tracing
# Capture BACKFILL_STARTED_AT from command output for rollback scope
php artisan tinker --execute="echo DB::table('sms_logs')->whereNull('message_uuid')->count() === 0 ? 'PASS' : 'FAIL';"
```
**STOP if FAIL. Execute rollback only.**

### 6. Rollback Path
```bash
php artisan tinker --execute="
\$startedAt = '<BACKFILL_STARTED_AT>';
DB::table('sms_logs')
  ->where('source', 'laravel')
  ->where('updated_at', '>=', \$startedAt)
  ->update(['message_uuid'=>null,'tenant_id'=>null]);
"
```

### 7. Artifacts Created/Changed
- `app/Console/Commands/BackfillSmsLogTracing.php`

### 8. Git Commit
```bash
git add app/Console/Commands/BackfillSmsLogTracing.php
git commit -m "feat: backfill sms_logs tracing (Step 4)"
```

### 9. Agent Prompt (Copy/Paste)
```
Execute Step 4: Create BackfillSmsLogTracing command, run it, verify PASS, commit if PASS.
```

---

## Step 5: Enforce message_uuid NOT NULL + UNIQUE

### 1. Purpose & Pre-requisites
Ensure idempotency key is enforced.

### 2. Files Involved
- `database/migrations/*_enforce_message_uuid_unique.php`

### 3. Commands to Run
```bash
php artisan make:migration enforce_message_uuid_unique
```

### 4. Precise Code Changes
```php
Schema::table('sms_logs', function (Blueprint $table) {
    $table->dropIndex(['message_uuid']);
    $table->char('message_uuid', 36)->nullable(false)->change();
    $table->unique('message_uuid');
});
```

**Down migration:**
```php
Schema::table('sms_logs', function (Blueprint $table) {
    $table->dropUnique(['message_uuid']);
    $table->char('message_uuid', 36)->nullable()->change();
    $table->index('message_uuid');
});
```

### 5. Verification Gate
```bash
php artisan tinker --execute="
\$nulls = DB::table('sms_logs')->whereNull('message_uuid')->count();
echo \$nulls === 0 ? 'PASS' : 'FAIL';
"
php artisan migrate
php artisan tinker --execute="
try {
  DB::table('sms_logs')->insert([
    'user_id'=>1,'tenant_id'=>1,'message_uuid'=>DB::table('sms_logs')->first()->message_uuid,
    'number'=>'x','message_id'=>'x','message'=>'x','gateway'=>'x','created_at'=>now(),'updated_at'=>now()
  ]);
  echo 'FAIL';
} catch (Exception \$e) {
  echo 'PASS';
}
"
```
**STOP if FAIL. Execute rollback only.**

### 6. Rollback Path
```bash
php artisan migrate:rollback --step=1
```

### 7. Artifacts Created/Changed
- `database/migrations/*_enforce_message_uuid_unique.php`

### 8. Git Commit
```bash
git add database/migrations/*enforce_message_uuid_unique*
git commit -m "feat: enforce message_uuid unique (Step 5)"
```

### 9. Agent Prompt (Copy/Paste)
```
Execute Step 5: Create message_uuid unique migration, run migrate, verify PASS, commit if PASS.
```

---

## Step 6: Create Feature Flags Table

### 1. Purpose & Pre-requisites
Tenant-level feature flag control for gradual rollout.

### 2. Files Involved
- `database/migrations/*_create_feature_flags_table.php`
- `app/Models/FeatureFlag.php`

### 3. Commands to Run
```bash
php artisan make:migration create_feature_flags_table
php artisan make:model FeatureFlag
```

### 4. Precise Code Changes

**Migration:**
```php
Schema::create('feature_flags', function (Blueprint $table) {
    $table->id();
    $table->unsignedBigInteger('tenant_id')->nullable();
    $table->string('feature_name', 100);
    $table->enum('mode', ['OFF', 'SHADOW', 'ON'])->default('OFF');
    $table->timestamps();
    $table->unique(['tenant_id', 'feature_name']);
});
DB::table('feature_flags')->insert([
    'tenant_id' => null,
    'feature_name' => 'messaging_service',
    'mode' => 'OFF',
    'created_at' => now(),
    'updated_at' => now()
]);
```

**Model:**
```php
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Facades\Cache;

class FeatureFlag extends Model
{
    protected $fillable = ['tenant_id', 'feature_name', 'mode'];

public static function getMode(string $feature, ?int $tenantId = null): string
    {
        $tenantId = $tenantId ?? resolveTenantId();
        $cacheKey = "feature_flag:{$feature}:tenant:" . ($tenantId ?? 'global');
        return Cache::remember($cacheKey, 60, function () use ($feature, $tenantId) {
            $flag = self::where('tenant_id', $tenantId)->where('feature_name', $feature)->first();
            if ($flag) return $flag->mode;
            $global = self::whereNull('tenant_id')->where('feature_name', $feature)->first();
            return $global ? $global->mode : 'OFF';
        });
    }
}
```

### 5. Verification Gate
```bash
php artisan migrate
php artisan tinker --execute="echo App\Models\FeatureFlag::getMode('messaging_service') === 'OFF' ? 'PASS' : 'FAIL';"
```
**STOP if FAIL. Execute rollback only.**

### 6. Rollback Path
```bash
php artisan migrate:rollback --step=1
rm app/Models/FeatureFlag.php
```

### 7. Artifacts Created/Changed
- `database/migrations/*_create_feature_flags_table.php`
- `app/Models/FeatureFlag.php`

### 8. Git Commit
```bash
git add database/migrations/*feature_flags* app/Models/FeatureFlag.php
git commit -m "feat: add feature_flags (Step 6)"
```

### 9. Agent Prompt (Copy/Paste)
```
Execute Step 6: Create feature_flags table + model, run migrate, verify PASS, commit if PASS.
```

---

## Step 7: Add Internal API Key + Service URL

### 1. Purpose & Pre-requisites
Secure internal calls to Go service.

### 2. Files Involved
- `.env`
- `.env.example`

### 3. Commands to Run
```bash
php artisan tinker --execute="echo base64_encode(random_bytes(32));"
```

### 4. Precise Code Changes
Add to `.env`:
```
INTERNAL_API_KEY=<generated>
MESSAGING_SERVICE_URL=http://localhost:8080
```

Add to `.env.example`:
```
INTERNAL_API_KEY=
MESSAGING_SERVICE_URL=
```

### 5. Verification Gate
```bash
php artisan tinker --execute="echo strlen(env('INTERNAL_API_KEY'))>=32 ? 'PASS' : 'FAIL';"
```
**STOP if FAIL. Execute rollback only.**

### 6. Rollback Path
Remove the lines from `.env` and `.env.example`.

### 7. Artifacts Created/Changed
- `.env`
- `.env.example`

### 8. Git Commit
```bash
git add .env.example
git commit -m "feat: add internal api key config (Step 7)"
```

### 9. Agent Prompt (Copy/Paste)
```
Execute Step 7: Add INTERNAL_API_KEY and MESSAGING_SERVICE_URL to envs. Commit .env.example only.
```

---

## Step 8: MessagingServiceClient + 500ms Budget

### 1. Purpose & Pre-requisites
Provide internal client with 500ms timeout budget for circuit breaker decisions.

### 2. Files Involved
- `app/Services/MessagingServiceClient.php`
- `config/services.php`

### 3. Commands to Run
```bash
mkdir -p app/Services
```

### 4. Precise Code Changes

**config/services.php (add):**
```php
'messaging' => [
    'url' => env('MESSAGING_SERVICE_URL', 'http://localhost:8080'),
],
```

**app/Services/MessagingServiceClient.php:**
```php
<?php
namespace App\Services;

use Illuminate\Support\Facades\Http;

class MessagingServiceClient
{
    private string $baseUrl;
    private string $apiKey;

public function __construct()
    {
        $this->baseUrl = config('services.messaging.url');
        $this->apiKey = env('INTERNAL_API_KEY', '');
    }

public function sendBatch(int $tenantId, array $messages, ?int $campaignId = null, bool $dryRun = false): array
    {
        // INVARIANT 2: UUID must be pre-generated by caller. Reject if missing.
        foreach ($messages as $msg) {
            if (empty($msg['message_uuid'])) {
                throw new \InvalidArgumentException('message_uuid is required for each message (Invariant 2)');
            }
        }

$response = Http::timeout(0.5)
            ->withHeaders(['X-Internal-API-Key' => $this->apiKey])
            ->post($this->baseUrl . '/internal/v1/sms/send-batch', [
                'tenant_id' => $tenantId,
                'campaign_id' => $campaignId,
                'messages' => $messages,
                'dry_run' => $dryRun
            ]);

if (!$response->successful()) {
            throw new \Exception("Messaging service error: " . $response->status());
        }
        return $response->json();
    }

public function isHealthy(): bool
    {
        try {
            return Http::timeout(0.5)->get($this->baseUrl . '/health')->successful();
        } catch (\Exception $e) {
            return false;
        }
    }
}
```

### 5. Verification Gate
```bash
php artisan tinker --execute="new App\Services\MessagingServiceClient(); echo 'PASS';"
```
**STOP if FAIL. Execute rollback only.**

### 6. Rollback Path
```bash
rm app/Services/MessagingServiceClient.php
git checkout HEAD -- config/services.php
```

### 7. Artifacts Created/Changed
- `app/Services/MessagingServiceClient.php`
- `config/services.php`

### 8. Git Commit
```bash
git add app/Services/MessagingServiceClient.php config/services.php
git commit -m "feat: add MessagingServiceClient (Step 8)"
```

### 9. Agent Prompt (Copy/Paste)
```
Execute Step 8: Add MessagingServiceClient with 500ms timeout, verify tinker PASS, commit if PASS.
```

---

## Step 9: Circuit Breaker + Fallback Verification Command

### 1. Purpose & Pre-requisites
Provide resilient fallback when Go fails or exceeds 500ms, and add an executable fallback verification command.

### 2. Files Involved
- `app/Services/CircuitBreaker.php`
- `app/Console/Commands/VerifyGoFallback.php`

### 3. Commands to Run
```bash
php artisan make:command VerifyGoFallback
```

### 4. Precise Code Changes

**app/Services/CircuitBreaker.php:**
```php
<?php
namespace App\Services;

use Illuminate\Support\Facades\Cache;

class CircuitBreaker
{
    private string $service;
    private int $threshold = 5;
    private int $timeout = 60;
    private int $halfOpenAttempts = 1;

public function __construct(string $service)
    {
        $this->service = $service;
    }

public function isOpen(): bool
    {
        return Cache::get("circuit:{$this->service}:open", false);
    }

public function allowRequest(): bool
    {
        if (!$this->isOpen()) {
            return true;
        }
        $attempts = (int) Cache::get("circuit:{$this->service}:half_open_attempts", 0);
        if ($attempts < $this->halfOpenAttempts) {
            Cache::put("circuit:{$this->service}:half_open_attempts", $attempts + 1, $this->timeout);
            return true;
        }
        return false;
    }

public function recordFailure(): void
    {
        $failures = Cache::increment("circuit:{$this->service}:failures");
        if ($failures >= $this->threshold) {
            Cache::put("circuit:{$this->service}:open", true, $this->timeout);
            Cache::forget("circuit:{$this->service}:failures");
            Cache::forget("circuit:{$this->service}:half_open_attempts");
        }
    }

public function recordSuccess(): void
    {
        Cache::forget("circuit:{$this->service}:failures");
        Cache::forget("circuit:{$this->service}:open");
        Cache::forget("circuit:{$this->service}:half_open_attempts");
    }
}
```

**app/Console/Commands/VerifyGoFallback.php:**
```php
<?php
namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;
use App\Services\CircuitBreaker;
use App\Services\MessagingServiceClient;

class VerifyGoFallback extends Command
{
    protected $signature = 'sms:verify-fallback';
    protected $description = 'Verify circuit breaker opens and fallback is used on Go failures';

public function handle()
    {
        Http::fake([
            '*' => Http::response(['error' => 'fail'], 500),
        ]);

$cb = new CircuitBreaker('messaging_service');
        $client = new MessagingServiceClient();

$tenantId = 1;
        $messages = [[
            'message_uuid' => (string) Str::uuid(),
            'recipient' => '+10000000000',
            'body' => 'test',
            'provider' => 'twilio'
        ]];

for ($i = 0; $i < 5; $i++) {
            try {
                $client->sendBatch($tenantId, $messages, null, true);
            } catch (\Exception $e) {
                $cb->recordFailure();
            }
        }

if (!$cb->isOpen()) {
            $this->error('FAIL: circuit did not open');
            return 1;
        }

$this->info('PASS: circuit open, fallback must be used in controller');
        return 0;
    }
}
```

### 5. Verification Gate
```bash
php artisan sms:verify-fallback
```
**STOP if FAIL. Execute rollback only.**

### 6. Rollback Path
```bash
rm app/Services/CircuitBreaker.php app/Console/Commands/VerifyGoFallback.php
```

### 7. Artifacts Created/Changed
- `app/Services/CircuitBreaker.php`
- `app/Console/Commands/VerifyGoFallback.php`

### 8. Git Commit
```bash
git add app/Services/CircuitBreaker.php app/Console/Commands/VerifyGoFallback.php
git commit -m "feat: add circuit breaker + fallback verification (Step 9)"
```

### 9. Agent Prompt (Copy/Paste)
```
Execute Step 9: Add CircuitBreaker + VerifyGoFallback command, run verification, commit if PASS.
```

---

## Step 10: Create go_sms_logs Table (Go Idempotency Store)

### 1. Purpose & Pre-requisites
Create Go-side log table for idempotency and reconciliation.

### 2. Files Involved
- `database/migrations/*_create_go_sms_logs_table.php`

### 3. Commands to Run
```bash
php artisan make:migration create_go_sms_logs_table
```

### 4. Precise Code Changes
```php
Schema::create('go_sms_logs', function (Blueprint $table) {
    $table->id();
    $table->char('message_uuid', 36)->unique();
    $table->unsignedBigInteger('tenant_id');
    $table->string('provider', 50);
    $table->boolean('dry_run')->default(false);
    $table->string('status', 20);
    $table->string('provider_message_id', 191)->nullable();
    $table->string('error_code', 50)->nullable();
    $table->longText('error_message')->nullable();
    $table->timestamps();

$table->index('tenant_id');
    $table->index(['status', 'created_at']);
});
```

### 5. Verification Gate
```bash
php artisan migrate
php artisan tinker --execute="
echo Schema::hasColumn('go_sms_logs','message_uuid') ? 'PASS' : 'FAIL';
"
php artisan tinker --execute="
\$driver = DB::getDriverName();
if (\$driver === 'mysql') {
  \$rows = DB::select(\"SELECT INDEX_NAME FROM information_schema.statistics WHERE table_schema = DATABASE() AND table_name = 'go_sms_logs' AND index_name = 'go_sms_logs_status_created_at_index'\");
} elseif (\$driver === 'pgsql') {
  \$rows = DB::select(\"SELECT indexname FROM pg_indexes WHERE tablename = 'go_sms_logs' AND indexname = 'go_sms_logs_status_created_at_index'\");
} else {
  \$rows = [];
}
echo count(\$rows) > 0 ? 'PASS' : 'FAIL';
"
```
**STOP if FAIL. Execute rollback only.**

### 6. Rollback Path
```bash
php artisan migrate:rollback --step=1
```

### 7. Artifacts Created/Changed
- `database/migrations/*_create_go_sms_logs_table.php`

### 8. Git Commit
```bash
git add database/migrations/*go_sms_logs*
git commit -m "feat: add go_sms_logs table (Step 10)"
```

### 9. Agent Prompt (Copy/Paste)
```
Execute Step 10: Create go_sms_logs migration, run migrate, verify PASS, commit if PASS.
```

---

## Step 11: Create Go Messaging Service Skeleton

### 1. Purpose & Pre-requisites
Create Go service with auth middleware and health endpoint.

### 2. Files Involved
- `services/messaging-service/go.mod`
- `services/messaging-service/cmd/server/main.go`
- `services/messaging-service/internal/middleware/auth.go`
- `services/messaging-service/internal/handlers/health.go`
- `services/messaging-service/internal/handlers/sms.go`
- `services/messaging-service/internal/models/models.go`
- `services/messaging-service/Makefile`

### 3. Commands to Run
```bash
mkdir -p services/messaging-service/cmd/server
mkdir -p services/messaging-service/internal/{middleware,handlers,models,providers,ratelimit,worker}
cd services/messaging-service
go mod init messaging-service
go get github.com/gin-gonic/gin@v1.9.1
go get gorm.io/gorm@v1.25.5
go get gorm.io/driver/mysql@v1.5.2
```

### 4. Precise Code Changes

**services/messaging-service/cmd/server/main.go:**
```go
package main

import (
	"log"
	"os"

"messaging-service/internal/handlers"
	"messaging-service/internal/middleware"

"github.com/gin-gonic/gin"
)

func main() {
	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
	}

r := gin.Default()
	r.GET("/health", handlers.Health)

internal := r.Group("/internal/v1")
	internal.Use(middleware.APIKeyAuth())
	internal.POST("/sms/send-batch", handlers.SendBatch)

log.Printf("Starting on :%s", port)
	r.Run(":" + port)
}
```

**services/messaging-service/internal/middleware/auth.go:**
```go
package middleware

import (
	"net/http"
	"os"

"github.com/gin-gonic/gin"
)

func APIKeyAuth() gin.HandlerFunc {
	return func(c *gin.Context) {
		key := c.GetHeader("X-Internal-API-Key")
		expected := os.Getenv("INTERNAL_API_KEY")
		if expected == "" || key != expected {
			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "unauthorized"})
			return
		}
		c.Next()
	}
}
```

**services/messaging-service/internal/handlers/health.go:**
```go
package handlers

import (
	"net/http"

"github.com/gin-gonic/gin"
)

func Health(c *gin.Context) {
	c.JSON(http.StatusOK, gin.H{"status": "healthy"})
}
```

**services/messaging-service/internal/models/models.go:**
```go
package models

import "time"

type SmsCredential struct {
	ID        uint   `gorm:"primaryKey"`
	OwnerID   uint   `gorm:"column:owner_id"`
	SmsName   string `gorm:"column:sms_name"`
	SmsID     string `gorm:"column:sms_id"`
	SmsToken  string `gorm:"column:sms_token"`
	SmsFrom   string `gorm:"column:sms_from"`
	SmsNumber string `gorm:"column:sms_number"`
	URL       string `gorm:"column:url"`
}

func (SmsCredential) TableName() string { return "sms" }

type SmsService struct {
	ID        uint   `gorm:"primaryKey"`
	OwnerID   uint   `gorm:"column:owner_id"`
	SmsName   string `gorm:"column:sms_name"`
	SmsID     string `gorm:"column:sms_id"`
	SmsToken  string `gorm:"column:sms_token"`
	SmsFrom   string `gorm:"column:sms_from"`
	SmsNumber string `gorm:"column:sms_number"`
	URL       string `gorm:"column:url"`
	Status    bool   `gorm:"column:status"`
}

func (SmsService) TableName() string { return "sms_services" }

type GoSmsLog struct {
	ID                uint      `gorm:"primaryKey"`
	MessageUUID       string    `gorm:"column:message_uuid"`
	TenantID          uint      `gorm:"column:tenant_id"`
	Provider          string    `gorm:"column:provider"`
	DryRun            bool      `gorm:"column:dry_run"`
	Status            string    `gorm:"column:status"`
	ProviderMessageID string    `gorm:"column:provider_message_id"`
	ErrorCode         string    `gorm:"column:error_code"`
	ErrorMessage      string    `gorm:"column:error_message"`
	CreatedAt         time.Time `gorm:"column:created_at"`
	UpdatedAt         time.Time `gorm:"column:updated_at"`
}

func (GoSmsLog) TableName() string { return "go_sms_logs" }
```

**services/messaging-service/Makefile:**
```makefile
run:
	: "$${DB_DSN?Set DB_DSN}"
	INTERNAL_API_KEY=test PORT=8080 DB_DSN=$$DB_DSN go run cmd/server/main.go
build:
	go build -o bin/server cmd/server/main.go
```

### 5. Verification Gate
```bash
cd services/messaging-service
go build -o /dev/null cmd/server/main.go && echo "Build PASS"
```
**STOP if FAIL. Execute rollback only.**

### 6. Rollback Path
```bash
rm -rf services/messaging-service
```

### 7. Artifacts Created/Changed
- `services/messaging-service/` directory

### 8. Git Commit
```bash
git add services/messaging-service/
git commit -m "feat: init go messaging service skeleton (Step 11)"
```

### 9. Agent Prompt (Copy/Paste)
```
Execute Step 11: Create Go service skeleton and build; commit if PASS.
```

---

## Step 12: Harden Go DB Lifecycle Determinism

### 1. Purpose & Pre-requisites
Ensure deterministic startup: if DB connection fails, service exits immediately with fatal log.

### 2. Files Involved
- `services/messaging-service/internal/handlers/sms.go`
- `services/messaging-service/internal/handlers/retry_test.go`

### 3. Commands to Run
N/A

### 4. Precise Code Changes
**In `services/messaging-service/internal/handlers/sms.go` init():**
```go
var db *gorm.DB

func init() {
	dsn := os.Getenv("DB_DSN")
	if dsn == "" {
		log.Fatal("DB_DSN is required")
	}
	var err error
	db, err = gorm.Open(mysql.Open(dsn), &gorm.Config{})
	if err != nil {
		log.Fatal("DB connection failed: ", err)
	}
}
```

### 5. Verification Gate
```bash
cd services/messaging-service
DB_DSN=invalid INTERNAL_API_KEY=test PORT=8080 go run cmd/server/main.go
```
**Expected:** process exits immediately with fatal log.  
**STOP if process keeps running. Execute rollback only.**

### 6. Rollback Path
```bash
git checkout HEAD -- services/messaging-service/internal/handlers/sms.go
rm services/messaging-service/internal/handlers/retry_test.go
```

### 7. Artifacts Created/Changed
- `services/messaging-service/internal/handlers/sms.go`
- `services/messaging-service/internal/handlers/retry_test.go`

### 8. Git Commit
```bash
git add services/messaging-service/internal/handlers/sms.go
git commit -m "fix: enforce fatal DB connection failure (Step 12)"
```

### 9. Agent Prompt (Copy/Paste)
```
Execute Step 12: Harden Go DB init to fail fast; verify invalid DB_DSN exits; commit if PASS.
```

---

## Step 13: Add Shared HTTP Client (Provider Timeout)

### 1. Purpose & Pre-requisites
Ensure provider requests have deterministic timeouts.

### 2. Files Involved
- `services/messaging-service/internal/providers/http_client.go`

### 3. Commands to Run
N/A

### 4. Precise Code Changes
```go
package providers

import (
    "net/http"
    "time"
)

var httpClient = &http.Client{
	Timeout: 5 * time.Second,
}
```

### 5. Verification Gate
```bash
cd services/messaging-service
go test ./...
```
**STOP if FAIL. Execute rollback only.**

### 6. Rollback Path
```bash
rm services/messaging-service/internal/providers/http_client.go
```

### 7. Artifacts Created/Changed
- `services/messaging-service/internal/providers/http_client.go`

### 8. Git Commit
```bash
git add services/messaging-service/internal/providers/http_client.go
git commit -m "feat: add provider http client timeout (Step 13)"
```

### 9. Agent Prompt (Copy/Paste)
```
Execute Step 13: Add shared http client timeout; run go test; commit if PASS.
```

---

## Step 14: Implement Worker Pool + Per-Tenant Rate Limiter + Tests

### 1. Purpose & Pre-requisites
Provide fixed worker pool and per-tenant token bucket limiter, with unit tests.

### 2. Files Involved
- `services/messaging-service/internal/worker/pool.go`
- `services/messaging-service/internal/worker/pool_test.go`
- `services/messaging-service/internal/ratelimit/tenant_limiter.go`
- `services/messaging-service/internal/ratelimit/tenant_limiter_test.go`

### 3. Commands to Run
N/A

### 4. Precise Code Changes

**services/messaging-service/internal/worker/pool.go:**
```go
package worker

import (
	"os"
	"strconv"
	"sync"
)

type Pool struct {
	wg   sync.WaitGroup
	jobs chan func()
}

func NewPool() *Pool {
	workers := 20
	if v := os.Getenv("WORKERS"); v != "" {
		if n, err := strconv.Atoi(v); err == nil && n > 0 {
			workers = n
		}
	}

p := &Pool{
		jobs: make(chan func()),
	}

for i := 0; i < workers; i++ {
		go func() {
			for job := range p.jobs {
				job()
				p.wg.Done()
			}
		}()
	}

return p
}

func (p *Pool) Submit(job func()) {
	p.wg.Add(1)
	p.jobs <- job
}

func (p *Pool) Wait() {
	p.wg.Wait()
}
```

**services/messaging-service/internal/worker/pool_test.go:**
```go
package worker

import (
	"sync/atomic"
	"testing"
)

func TestPoolExecutesJobs(t *testing.T) {
	p := NewPool()
	var count int32
	for i := 0; i < 10; i++ {
		p.Submit(func() {
			atomic.AddInt32(&count, 1)
		})
	}
	p.Wait()
	if count != 10 {
		t.Fatalf("expected 10, got %d", count)
	}
}
```

**services/messaging-service/internal/ratelimit/tenant_limiter.go:**
```go
package ratelimit

import (
	"os"
	"strconv"
	"sync"
	"time"
)

type tokenBucket struct {
	capacity int
	tokens   float64
	last     time.Time
	rate     float64
}

type TenantLimiter struct {
	mu      sync.Mutex
	buckets map[uint]*tokenBucket
	rate    float64
	burst   int
}

func NewTenantLimiter() *TenantLimiter {
	rate := 10.0
	if v := os.Getenv("TENANT_RPS"); v != "" {
		if n, err := strconv.Atoi(v); err == nil && n > 0 {
			rate = float64(n)
		}
	}
	burst := 20
	if v := os.Getenv("TENANT_BURST"); v != "" {
		if n, err := strconv.Atoi(v); err == nil && n > 0 {
			burst = n
		}
	}
	return &TenantLimiter{
		buckets: map[uint]*tokenBucket{},
		rate:    rate,
		burst:   burst,
	}
}

func (l *TenantLimiter) Allow(tenantID uint) bool {
	l.mu.Lock()
	defer l.mu.Unlock()

b, ok := l.buckets[tenantID]
	if !ok {
		b = &tokenBucket{capacity: l.burst, tokens: float64(l.burst), last: time.Now(), rate: l.rate}
		l.buckets[tenantID] = b
	}

now := time.Now()
	elapsed := now.Sub(b.last).Seconds()
	b.tokens = min(float64(b.capacity), b.tokens+elapsed*b.rate)
	b.last = now

if b.tokens >= 1 {
		b.tokens -= 1
		return true
	}
	return false
}

func min(a, b float64) float64 {
	if a < b {
		return a
	}
	return b
}
```

**services/messaging-service/internal/ratelimit/tenant_limiter_test.go:**
```go
package ratelimit

import "testing"

func TestLimiterIsPerTenant(t *testing.T) {
	l := NewTenantLimiter()

// Exhaust tenant 1
	for i := 0; i < 100; i++ {
		l.Allow(1)
	}

// Tenant 2 should still be allowed initially
	if !l.Allow(2) {
		t.Fatalf("tenant 2 should not be starved by tenant 1")
	}
}
```

### 5. Verification Gate
```bash
cd services/messaging-service
go test ./...
```
**STOP if FAIL. Execute rollback only.**

### 6. Rollback Path
```bash
rm services/messaging-service/internal/worker/pool.go services/messaging-service/internal/worker/pool_test.go
rm services/messaging-service/internal/ratelimit/tenant_limiter.go services/messaging-service/internal/ratelimit/tenant_limiter_test.go
```

### 7. Artifacts Created/Changed
- `services/messaging-service/internal/worker/pool.go`
- `services/messaging-service/internal/worker/pool_test.go`
- `services/messaging-service/internal/ratelimit/tenant_limiter.go`
- `services/messaging-service/internal/ratelimit/tenant_limiter_test.go`

### 8. Git Commit
```bash
git add services/messaging-service/internal/worker/pool.go services/messaging-service/internal/worker/pool_test.go
git add services/messaging-service/internal/ratelimit/tenant_limiter.go services/messaging-service/internal/ratelimit/tenant_limiter_test.go
git commit -m "feat: worker pool + tenant limiter + tests (Step 14)"
```

### 9. Agent Prompt (Copy/Paste)
```
Execute Step 14: Add worker pool + rate limiter + tests; run go test; commit if PASS.
```

---

## Step 15: Implement Go Idempotency + Logging (go_sms_logs)

### 1. Purpose & Pre-requisites
Prevent duplicate sends by `message_uuid`, log deterministic responses, and enforce dry_run behavior.

### 2. Files Involved
- `services/messaging-service/internal/handlers/sms.go`

### 3. Commands to Run
N/A

### 4. Precise Code Changes

**Replace `services/messaging-service/internal/handlers/sms.go` with:**
```go
package handlers

import (
	"errors"
	"log"
	"math/rand"
	"net"
	"net/http"
	"os"
	"strings"
	"sync"
	"time"

"github.com/gin-gonic/gin"
	"gorm.io/driver/mysql"
	"gorm.io/gorm"

"messaging-service/internal/models"
	"messaging-service/internal/providers"
	"messaging-service/internal/ratelimit"
	"messaging-service/internal/worker"
)

var db *gorm.DB

type Message struct {
	MessageUUID string `json:"message_uuid" binding:"required"`
	Recipient   string `json:"recipient" binding:"required"`
	Body        string `json:"body" binding:"required"`
	Provider    string `json:"provider" binding:"required"`
}

type SendBatchRequest struct {
	TenantID   int       `json:"tenant_id" binding:"required"`
	CampaignID *int      `json:"campaign_id"`
	Messages   []Message `json:"messages" binding:"required"`
	DryRun     bool      `json:"dry_run"`
}

type SendResult struct {
	MessageUUID       string `json:"message_uuid"`
	Status            string `json:"status"`
	ProviderMessageID string `json:"provider_message_id"`
	ErrorCode         string `json:"error_code"`
	ErrorMessage      string `json:"error_message"`
}

func loadCredentials(tenantID int, provider string) (models.SmsCredential, error) {
	var svc models.SmsService
	if err := db.Where("owner_id = ? AND sms_name = ? AND status = ?", tenantID, provider, true).First(&svc).Error; err == nil {
		return models.SmsCredential{
			OwnerID:   svc.OwnerID,
			SmsName:   svc.SmsName,
			SmsID:     svc.SmsID,
			SmsToken:  svc.SmsToken,
			SmsFrom:   svc.SmsFrom,
			SmsNumber: svc.SmsNumber,
			URL:       svc.URL,
		}, nil
	}

var cred models.SmsCredential
	if err := db.Where("owner_id = ? AND sms_name = ?", tenantID, provider).First(&cred).Error; err != nil {
		if errors.Is(err, gorm.ErrRecordNotFound) {
			return models.SmsCredential{}, errors.New("credentials not found for provider: " + provider)
		}
		return models.SmsCredential{}, err
	}
	return cred, nil
}

func loadExistingLog(messageUUID string) (*models.GoSmsLog, error) {
	var logEntry models.GoSmsLog
	if err := db.Where("message_uuid = ?", messageUUID).First(&logEntry).Error; err != nil {
		return nil, err
	}
	return &logEntry, nil
}

func createLog(entry *models.GoSmsLog) error {
	return db.Create(entry).Error
}

func updateLog(entry *models.GoSmsLog, status, providerMessageID, errorCode, errorMessage string) {
	db.Model(entry).Updates(map[string]interface{}{
		"status":              status,
		"provider_message_id": providerMessageID,
		"error_code":          errorCode,
		"error_message":       errorMessage,
		"updated_at":          time.Now(),
	})
}

func SendBatch(c *gin.Context) {
	var req SendBatchRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}

workers := worker.NewPool()
	limiter := ratelimit.NewTenantLimiter()
	var resultsMu sync.Mutex

results := make([]SendResult, len(req.Messages))

for i, msg := range req.Messages {
		if existing, err := loadExistingLog(msg.MessageUUID); err == nil {
			resultsMu.Lock()
			results[i] = SendResult{
				MessageUUID:       existing.MessageUUID,
				Status:            "duplicate",
				ProviderMessageID: existing.ProviderMessageID,
				ErrorCode:         existing.ErrorCode,
				ErrorMessage:      existing.ErrorMessage,
			}
			resultsMu.Unlock()
			continue
		}

if !limiter.Allow(uint(req.TenantID)) {
			resultsMu.Lock()
			results[i] = SendResult{
				MessageUUID:  msg.MessageUUID,
				Status:       "rejected",
				ErrorCode:    "RATE_LIMIT",
				ErrorMessage: "tenant rate limit exceeded",
			}
			resultsMu.Unlock()
			continue
		}

entry := &models.GoSmsLog{
			MessageUUID: msg.MessageUUID,
			TenantID:    uint(req.TenantID),
			Provider:    msg.Provider,
			DryRun:      req.DryRun,
			Status:      "queued",
		}
		if err := createLog(entry); err != nil {
			resultsMu.Lock()
			results[i] = SendResult{
				MessageUUID:  msg.MessageUUID,
				Status:       "rejected",
				ErrorCode:    "LOG_CREATE_FAILED",
				ErrorMessage: err.Error(),
			}
			resultsMu.Unlock()
			continue
		}

index := i
		message := msg
		workers.Submit(func() {
			if req.DryRun {
				log.Printf("DRY_RUN_NO_PROVIDER_CALL: message_uuid=%s", message.MessageUUID)
				updateLog(entry, "accepted", "", "", "")
				resultsMu.Lock()
				results[index] = SendResult{
					MessageUUID: message.MessageUUID,
					Status:      "accepted",
				}
				resultsMu.Unlock()
				return
			}

cred, err := loadCredentials(req.TenantID, message.Provider)
			if err != nil {
				updateLog(entry, "rejected", "", "CREDENTIALS_NOT_FOUND", err.Error())
				resultsMu.Lock()
				results[index] = SendResult{
					MessageUUID:  message.MessageUUID,
					Status:       "rejected",
					ErrorCode:    "CREDENTIALS_NOT_FOUND",
					ErrorMessage: err.Error(),
				}
				resultsMu.Unlock()
				return
			}

providerMsgID, err := retrySend(func() (string, error) {
				return providers.Send(message.Provider, cred.SmsID, cred.SmsToken, cred.SmsFrom, cred.URL, message.Recipient, message.Body)
			})
			if err != nil {
				updateLog(entry, "rejected", "", "PROVIDER_ERROR", err.Error())
				resultsMu.Lock()
				results[index] = SendResult{
					MessageUUID:  message.MessageUUID,
					Status:       "rejected",
					ErrorCode:    "PROVIDER_ERROR",
					ErrorMessage: err.Error(),
				}
				resultsMu.Unlock()
				return
			}

updateLog(entry, "accepted", providerMsgID, "", "")
			resultsMu.Lock()
			results[index] = SendResult{
				MessageUUID:       message.MessageUUID,
				Status:            "accepted",
				ProviderMessageID: providerMsgID,
			}
			resultsMu.Unlock()
		})
	}

workers.Wait()

accepted := 0
	for _, r := range results {
		if r.Status == "accepted" || r.Status == "duplicate" {
			accepted++
		}
	}

c.JSON(http.StatusOK, gin.H{
		"batch_id": "batch-" + req.Messages[0].MessageUUID[:8],
		"total":    len(req.Messages),
		"accepted": accepted,
		"rejected": len(req.Messages) - accepted,
		"results":  results,
	})
}

func retrySend(sendFn func() (string, error)) (string, error) {
	const maxAttempts = 3
	const maxTotal = 2 * time.Second
	start := time.Now()

var lastErr error
	for attempt := 1; attempt <= maxAttempts; attempt++ {
		msgID, err := sendFn()
		if err == nil {
			return msgID, nil
		}
		lastErr = err
		if !isTransient(err) || time.Since(start) >= maxTotal {
			break
		}
		// exponential backoff with jitter, bounded by total budget
		backoff := time.Duration(100*(1<<uint(attempt-1))) * time.Millisecond
		jitter := time.Duration(rand.Intn(50)) * time.Millisecond
		sleep := backoff + jitter
		if time.Since(start)+sleep > maxTotal {
			break
		}
		time.Sleep(sleep)
	}
	return "", lastErr
}

func isTransient(err error) bool {
	if err == nil {
		return false
	}
	if strings.Contains(err.Error(), "REAL_SEND_BLOCKED") {
		return false
	}
	if nerr, ok := err.(net.Error); ok && (nerr.Timeout() || nerr.Temporary()) {
		return true
	}
	// best-effort string checks for 5xx/timeout/dns
	msg := strings.ToLower(err.Error())
	if strings.Contains(msg, "timeout") || strings.Contains(msg, "temporary") || strings.Contains(msg, "dns") {
		return true
	}
	if strings.Contains(msg, " 5") || strings.Contains(msg, "503") || strings.Contains(msg, "502") || strings.Contains(msg, "504") {
		return true
	}
	return false
}
```

**services/messaging-service/internal/handlers/retry_test.go:**
```go
package handlers

import (
	"errors"
	"net"
	"testing"
)

func TestRetrySendNoRetryOnRealSendBlocked(t *testing.T) {
	attempts := 0
	_, err := retrySend(func() (string, error) {
		attempts++
		return "", errors.New("REAL_SEND_BLOCKED: set ALLOW_REAL_SEND=true")
	})
	if err == nil {
		t.Fatalf("expected error")
	}
	if attempts != 1 {
		t.Fatalf("expected 1 attempt, got %d", attempts)
	}
}

func TestRetrySendRetriesTransientThenSucceeds(t *testing.T) {
	attempts := 0
	_, err := retrySend(func() (string, error) {
		attempts++
		if attempts < 3 {
			return "", &net.DNSError{IsTemporary: true}
		}
		return "ok", nil
	})
	if err != nil {
		t.Fatalf("unexpected error: %v", err)
	}
	if attempts != 3 {
		t.Fatalf("expected 3 attempts, got %d", attempts)
	}
}
```

### 5. Verification Gate
```bash
cd services/messaging-service
go build -o /dev/null cmd/server/main.go && echo "Build PASS"
go test -race ./...
```
**STOP if FAIL. Execute rollback only.**

### 6. Rollback Path
```bash
git checkout HEAD -- services/messaging-service/internal/handlers/sms.go
```

### 7. Artifacts Created/Changed
- `services/messaging-service/internal/handlers/sms.go`

### 8. Git Commit
```bash
git add services/messaging-service/internal/handlers/sms.go services/messaging-service/internal/handlers/retry_test.go
git commit -m "feat: go idempotency + logging (Step 15)"
```

### 9. Agent Prompt (Copy/Paste)
```
Execute Step 15: Implement Go idempotency + logging, build, commit if PASS.
```

---

## Step 16: Implement Go Providers (Like-for-Like)

### 1. Purpose & Pre-requisites
Support all Laravel SMS providers. Use credentials from `sms` or `sms_services`. No hardcoded credentials. Dry-run must not send.

### 2. Files Involved
- `services/messaging-service/internal/providers/router.go`
- `services/messaging-service/internal/providers/*.go`

### 3. Commands to Run
```bash
cd services/messaging-service
go get github.com/twilio/twilio-go@v1.15.0
go get github.com/vonage/vonage-go-sdk@v0.14.1
go get github.com/plivo/plivo-go/v7@v7.29.0
```

### 4. Precise Code Changes

**services/messaging-service/internal/providers/router.go:**
```go
package providers

import (
	"errors"
	"os"
)

func Send(provider, sid, token, from, baseURL, to, body string) (string, error) {
	if os.Getenv("ALLOW_REAL_SEND") != "true" {
		return "", errors.New("REAL_SEND_BLOCKED: set ALLOW_REAL_SEND=true")
	}

switch provider {
	case "twilio":
		return SendTwilio(sid, token, from, to, body)
	case "nexmo":
		return SendNexmo(sid, token, from, to, body)
	case "textlocal":
		return SendTextLocal(sid, token, from, to, body)
	case "plivo":
		return SendPlivo(sid, token, from, to, body)
	case "signalwire":
		return SendSignalwire(sid, token, from, to, body)
	case "infobip":
		return SendInfobip(sid, baseURL, from, to, body)
	case "viber":
		return SendViber(token, from, to, body)
	case "whatsapp":
		return SendWhatsApp(token, from, to, body)
	case "telesign":
		return SendTelesign(sid, token, from, to, body)
	case "sinch":
		return SendSinch(sid, token, from, to, body)
	case "clickatell":
		return SendClickatell(token, from, to, body)
	case "mailjet":
		return SendMailjet(to, from, body, token)
	case "lao":
		return SendLao(baseURL, sid, token, from, to, body)
	case "aakash":
		return SendAakash(sid, from, to, body)
	default:
		return "", errors.New("unsupported provider: " + provider)
	}
}
```

**services/messaging-service/internal/providers/twilio.go:**
```go
package providers

import (
	"github.com/twilio/twilio-go"
	api "github.com/twilio/twilio-go/rest/api/v2010"
)

func SendTwilio(sid, token, from, to, body string) (string, error) {
	client := twilio.NewRestClientWithParams(twilio.ClientParams{
		Username: sid,
		Password: token,
	})
	params := &api.CreateMessageParams{}
	params.SetTo(to)
	params.SetFrom(from)
	params.SetBody(body)
	resp, err := client.Api.CreateMessage(params)
	if err != nil {
		return "", err
	}
	return *resp.Sid, nil
}
```

**services/messaging-service/internal/providers/nexmo.go:**
```go
package providers

import "github.com/vonage/vonage-go-sdk"

func SendNexmo(apiKey, apiSecret, from, to, body string) (string, error) {
	auth := vonage.CreateAuthFromKeySecret(apiKey, apiSecret)
	client := vonage.NewSMSClient(auth)
	resp, _, err := client.Send(from, to, body, vonage.SMSOpts{})
	if err != nil {
		return "", err
	}
	if len(resp.Messages) > 0 {
		return resp.Messages[0].MessageID, nil
	}
	return "", nil
}
```

**services/messaging-service/internal/providers/textlocal.go:**
```go
package providers

import (
	"net/http"
	"net/url"
)

func SendTextLocal(apiKey, _, sender, to, body string) (string, error) {
	params := url.Values{
		"apikey":  {apiKey},
		"numbers": {to},
		"message": {body},
		"sender":  {sender},
	}
	resp, err := httpClient.Get("https://api.textlocal.in/send/?" + params.Encode())
	if err != nil {
		return "", err
	}
	defer resp.Body.Close()
	return "textlocal-" + to, nil
}
```

**services/messaging-service/internal/providers/plivo.go:**
```go
package providers

import "github.com/plivo/plivo-go/v7"

func SendPlivo(authID, authToken, from, to, body string) (string, error) {
	client, err := plivo.NewClient(authID, authToken, &plivo.ClientOptions{})
	if err != nil {
		return "", err
	}
	resp, err := client.Messages.Create(plivo.MessageCreateParams{Src: from, Dst: to, Text: body})
	if err != nil {
		return "", err
	}
	return resp.MessageUUID, nil
}
```

**services/messaging-service/internal/providers/signalwire.go:**
```go
package providers

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func SendSignalwire(projectID, apiToken, from, to, body string) (string, error) {
	url := fmt.Sprintf("https://%s.signalwire.com/api/laml/2010-04-01/Accounts/%s/Messages.json", projectID, projectID)
	data := fmt.Sprintf("From=%s&To=%s&Body=%s", from, to, body)
	req, _ := http.NewRequest("POST", url, bytes.NewBufferString(data))
	req.SetBasicAuth(projectID, apiToken)
	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
	resp, err := httpClient.Do(req)
	if err != nil {
		return "", err
	}
	defer resp.Body.Close()
	var result struct{ Sid string `json:"sid"` }
	json.NewDecoder(resp.Body).Decode(&result)
	return result.Sid, nil
}
```

**services/messaging-service/internal/providers/infobip.go:**
```go
package providers

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func SendInfobip(apiKey, baseURL, from, to, body string) (string, error) {
	payload := map[string]interface{}{
		"messages": []map[string]interface{}{
			{"from": from, "destinations": []map[string]string{{"to": to}}, "text": body},
		},
	}
	jsonData, _ := json.Marshal(payload)
	req, _ := http.NewRequest("POST", fmt.Sprintf("https://%s/sms/2/text/advanced", baseURL), bytes.NewBuffer(jsonData))
	req.Header.Set("Authorization", "App "+apiKey)
	req.Header.Set("Content-Type", "application/json")
	resp, err := httpClient.Do(req)
	if err != nil {
		return "", err
	}
	defer resp.Body.Close()
	var result struct {
		Messages []struct {
			MessageId string `json:"messageId"`
		} `json:"messages"`
	}
	json.NewDecoder(resp.Body).Decode(&result)
	if len(result.Messages) > 0 {
		return result.Messages[0].MessageId, nil
	}
	return "", nil
}
```

**services/messaging-service/internal/providers/viber.go:**
```go
package providers