Briefing obligatorio del paquete sunnyface/ai-contracts. Activa SIEMPRE que toques DTOs, webhooks, comunicación Hub-Spoke, o el namespace Sunnyface\Contracts. Contiene reglas irrompibles y dónde leer los contratos reales en vendor/.
Estás en un proyecto consumidor del paquete sunnyface/ai-contracts — el Single Source of Truth de toda la comunicación Hub↔Spoke. Lee esto antes de escribir código relacionado con DTOs o webhooks.
El propietario es Kiko. Ningún agente tiene autorización para modificar el paquete. Si detectas un problema, reporta el archivo y la línea exacta, y espera instrucciones.
PROHIBIDO crear, editar o eliminar archivos en vendor/sunnyface/ai-contracts/
Sin excepciones. El código correcto vive en app/ y tests/ del proyecto actual.
Antes de usar un DTO, lee su firma directamente en vendor/. El código es la verdad, no ningún documento.
vendor/sunnyface/ai-contracts/src/
├── Data/
│ ├── Network/ ← Webhooks Hub→Spoke (entrantes al Spoke)
│ ├── Spoke/ ← Requests Spoke→Hub (salientes del Spoke)
│ │ └── Responses/ ← Responses que el Hub devuelve
│ ├── Agent/ ← Config de agentes
│ ├── Llm/ ← Mensajes, citas, contexto cognitivo
│ ├── Governance/ ← Insights de gobernanza
│ ├── Metrics/ ← Métricas de uso
│ ├── Vault/ ← Entidades de vault
│ ├── Extractor/ ← Config de extractores
│ ├── Classifier/ ← Config de clasificadores
│ ├── FinancialExtraction/ ← Extracción financiera
│ └── Translator/ ← Traducción
└── Enums/ ← Todos los enums del sistema
public function handle(SomeHubWebhookDTO $dto, ProcessAction $action): ResponseDTO
{
return $action->execute($dto);
}
Responsable) — nunca response()->json().// CORRECTO
/** @var array<int, AgentSummaryData>|null */
public readonly ?array $agents = null;
// PROHIBIDO — Spatie Data v4 no usa DataCollectionOf en este paquete
#[DataCollectionOf(AgentSummaryData::class)]
public readonly ?DataCollection $agents = null;
Solo reciben DTOs o primitivos. Nunca usan request(), response(), redirect(). Si algo falla, lanzan excepciones de dominio. El handler de excepciones de Laravel traduce a HTTP.
Header: X-Sunnyface-Signature (HMAC-SHA256 con hash_equals()).
Si el trabajo requiere un DTO nuevo, campo adicional, o enum nuevo:
composer update sunnyface/ai-contracts y continúas.No improvises contratos. Un DTO incorrecto rompe Hub y todos los Spokes.
Para anti-patrones detectados, async, Livewire + Spatie Data, y HubCommunicationService:
/perfect-agent-guide