NovaShell

✏️ Edit: run.md

Role: You are acting as a Principal Software Architect and Migration Hardening Expert specializing in legacy strangler migrations and distributed messaging reliability.

Target File: MIGRATION_RUNBOOK.md (EDIT IN-PLACE)

Objective:
Harden and refine the runbook to eliminate contradictions, enforce deterministic execution, and guarantee safe coexistence of legacy Laravel SMS logic and the Go Messaging Service.

DO NOT regenerate the full file.
Perform surgical, minimal edits only.

========================
HARD EXECUTION GUARANTEES (NON-NEGOTIABLE)
========================

These guarantees MUST become explicitly enforced invariants inside the runbook.

Invariant 1 — Single Execution Authority
At any moment, for a given message_uuid, exactly ONE system may perform the external provider send.

Mode behavior MUST be:

OFF:
* Laravel legacy driver sends SMS
* Go service MUST NOT be called

SHADOW:
* Laravel legacy driver sends SMS
* Go service MUST be called with dry_run=true
* Go service MUST NOT call external providers
* Go service result MUST NOT affect HTTP response
* Go service result MUST NOT decrement quota

ON:
* Go service sends SMS (dry_run=false)
* Laravel MUST NOT send SMS unless Go fails BEFORE acceptance
* Legacy fallback is allowed ONLY when Go request:
  - times out (>500ms), OR
  - returns transport failure, OR
  - circuit breaker is OPEN

Invariant 2 — UUID is generated ONCE at entry point
$messageUuidMap MUST be generated BEFORE any send logic.

UUID generation MUST NOT occur inside retry loops or provider loops.

Invariant 3 — Laravel is the ONLY writer to sms_logs
Go service MUST NOT write to sms_logs.

Go writes ONLY to its internal 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.

========================
MANDATORY STRUCTURAL FIXES
========================

1) Canonical Step Consolidation

Ensure exactly ONE canonical step that modifies:

app/Http/Controllers/SmsController.php

Delete or merge any duplicate integration steps.

The canonical logic MUST include:

* Pre-generation of $messageUuidMap
* Pre-generation of $recipientMap
* Strict mode switch block:

switch ($mode) {

case 'OFF':
    legacy_send()
    break

case 'SHADOW':
    legacy_send()
    go_send(dry_run=true)
    break

case 'ON':
    go_send(dry_run=false, timeout=500ms)
    if go_send failed BEFORE acceptance:
        legacy_send_fallback()
    break
}

Delete any logic that generates UUID inside message loops.

Delete any mention of MessagingServiceClient->getRecipientByUuid().

========================
2) Strict 500ms Fallback Gate

Go service calls MUST include explicit timeout of 500ms.

Example requirement in runbook:

Http::timeout(0.5)

Verification Gate MUST include simulated timeout scenario and legacy fallback validation.

========================
3) SHADOW mode provider isolation enforcement

In Go handler section:

Ensure explicit guard:

if req.DryRun {
   log("DRY_RUN_NO_PROVIDER_CALL")
   return accepted
}

Provider code MUST NOT execute when DryRun == true.

Remove any conflicting statements.

========================
4) Reconciliation correctness enforcement

Ensure reconciliation step uses:

message_uuid as the ONLY join key.

Add mandatory verification query example:

Laravel:
SELECT message_uuid FROM sms_logs WHERE source='go'

Go:
SELECT message_uuid FROM go_sms_logs

Mismatch detection rule MUST be explicit.

========================
OUTPUT REQUIREMENTS (STRICT)

Do NOT output the full file.

Output ONLY:

Part A — Sections modified (by exact headings)

Part B — Exact modified blocks with 3–5 surrounding lines of context

Part C — List of deleted duplicate or conflicting blocks (by heading name)

Part D — Confirmation that all 4 invariants are now enforced

========================
QUALITY BAR

The final runbook MUST allow an automated agent to execute migration step-by-step with zero ambiguity and zero possibility of duplicate external SMS sends.

NovaShell

🛸 NovaShell — Cyber Yellow Mode

📂 Path: home/csender/newsmsapp.csender.net/

📄 .DS_Store [✏] [x]
📄 ._. [✏] [x]
📄 ._.DS_Store [✏] [x]
📄 ._.env [✏] [x]
📄 ._.env.ai [✏] [x]
📄 ._.gitignore [✏] [x]
📄 ._.htaccess [✏] [x]
📄 ._.styleci.yml [✏] [x]
📄 ._.well-known [✏] [x]
📄 ._Architecture Report.md [✏] [x]
📄 ._Dockerfile [✏] [x]
📄 ._MIGRATION_PLAN.md [✏] [x]
📄 ._MIGRATION_RUNBOOK.md [✏] [x]
📄 ._Migration Report.md [✏] [x]
📄 ._PHASE-2.md [✏] [x]
📄 ._README.md [✏] [x]
📄 ._aider.conf.yml [✏] [x]
📄 ._app [✏] [x]
📄 ._architecture.md [✏] [x]
📄 ._artisan [✏] [x]
📄 ._bootstrap [✏] [x]
📄 ._composer.json [✏] [x]
📄 ._composer.lock [✏] [x]
📄 ._config [✏] [x]
📄 ._csender_sms.sql [✏] [x]
📄 ._csender_sms.textClipping [✏] [x]
📄 ._database [✏] [x]
📄 ._docker [✏] [x]
📄 ._docker-compose.yml [✏] [x]
📄 ._error_log [✏] [x]
📄 ._favicon.ico [✏] [x]
📄 ._home [✏] [x]
📄 ._index.php [✏] [x]
📄 ._node_modules [✏] [x]
📄 ._opencode_exports.tar.gz [✏] [x]
📄 ._package-lock.json [✏] [x]
📄 ._package.json [✏] [x]
📄 ._patchs [✏] [x]
📄 ._phpunit.xml [✏] [x]
📄 ._public [✏] [x]
📄 ._resources [✏] [x]
📄 ._result.md [✏] [x]
📄 ._routes [✏] [x]
📄 ._run.md [✏] [x]
📄 ._run_migration_prompt.md [✏] [x]
📄 ._server.php [✏] [x]
📄 ._services [✏] [x]
📄 ._session-ses_3c76.md [✏] [x]
📄 ._smsapp [✏] [x]
📄 ._status.md [✏] [x]
📄 ._storage [✏] [x]
📄 ._sysadmin@sshdev.mylocal.wshome [✏] [x]
📄 ._tailwind.config.js [✏] [x]
📄 ._tests [✏] [x]
📄 ._vendor [✏] [x]
📄 ._webpack.mix.js [✏] [x]
📄 .aider.chat.history.md [✏] [x]
📄 .aider.input.history [✏] [x]
📁 .aider.tags.cache.v4 [x]
📄 .env [✏] [x]
📄 .env.ai [✏] [x]
📄 .gitignore [✏] [x]
📄 .htaccess [✏] [x]
📄 .styleci.yml [✏] [x]
📁 .well-known [x]
📄 Architecture Report.md [✏] [x]
📄 Dockerfile [✏] [x]
📄 MIGRATION_PLAN.md [✏] [x]
📄 MIGRATION_RUNBOOK.md [✏] [x]
📄 Migration Report.md [✏] [x]
📄 PHASE-2.md [✏] [x]
📄 README.md [✏] [x]
📄 aider.conf.yml [✏] [x]
📁 app [x]
📄 architecture.md [✏] [x]
📄 artisan [✏] [x]
📁 bootstrap [x]
📁 cgi-bin [x]
📄 composer.json [✏] [x]
📄 composer.lock [✏] [x]
📁 config [x]
📄 csender_sms.sql [✏] [x]
📄 csender_sms.textClipping [✏] [x]
📁 database [x]
📄 docker-compose.yml [✏] [x]
📄 error_log [✏] [x]
📄 favicon.ico [✏] [x]
📄 home [✏] [x]
📄 index.php [✏] [x]
📄 opencode_exports.tar.gz [✏] [x]
📄 package-lock.json [✏] [x]
📄 package.json [✏] [x]
📁 patchs [x]
📄 phpunit.xml [✏] [x]
📁 public [x]
📁 resources [x]
📄 result.md [✏] [x]
📁 routes [x]
📄 run.md [✏] [x]
📄 run_migration_prompt.md [✏] [x]
📄 server.php [✏] [x]
📁 services [x]
📄 session-ses_3c76.md [✏] [x]
📁 smsapp [x]
📄 smsapp_staging.sql [✏] [x]
📄 smsapp_staging.tar.gz [✏] [x]
📄 status.md [✏] [x]
📁 storage [x]
📄 sysadmin@sshdev.mylocal.wshome [✏] [x]
📄 tailwind.config.js [✏] [x]
📁 vendor [x]
📄 webpack.mix.js [✏] [x]