arckode-framework 1.2.2 → 1.2.3

package/cli/stubs/module-stub.ts

@@ -200,8 +200,18 @@ export class ${p.name}Service {
     private readonly cache: CacheAdapter,
   ) {}
 
+  // ACUMULA handlers — nunca pisa el anterior.
+  // Si dos conectores registran el mismo evento, ambos corren en cadena (secuencial).
+  // Para ejecución paralela independiente → usar EventBus en composition-root.ts.
   setSockets(s: Partial<${p.name}Sockets>): void {
-    this.sockets = { ...this.sockets, ...s }
+    const next = s as Record<string, any>
+    const cur = this.sockets as Record<string, any>
+    for (const key of Object.keys(next)) {
+      const h = next[key]
+      if (!h) continue
+      const prev = cur[key]
+      cur[key] = prev ? async (...a: any[]) => { await prev(...a); await h(...a) } : h
+    }
   }
 
   async list(query?: ${p.name}Query): Promise<${p.name}Paginated> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arckode-framework",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "AI-first TypeScript/Bun framework. Modular, SOLID, zero magic. The AI reads the composition root and knows everything.",
   "type": "module",
   "main": "./kernel/framework.ts",

package/skills/connectors/SKILL.md

@@ -66,9 +66,17 @@ import type { PedidosSockets } from './sockets'
 export class PedidosService {
   private sockets: PedidosSockets = {}
 
-  // MERGE — no replace. Si dos conectores inyectan sockets, el segundo no pisa al primero.
+  // ACUMULA — si dos conectores registran el mismo evento, ambos corren en cadena.
+  // NUNCA usar { ...this.sockets, ...s } — pisa silenciosamente el handler anterior.
   setSockets(s: Partial<PedidosSockets>): void {
-    this.sockets = { ...this.sockets, ...s }
+    const next = s as Record<string, any>
+    const cur = this.sockets as Record<string, any>
+    for (const key of Object.keys(next)) {
+      const h = next[key]
+      if (!h) continue
+      const prev = cur[key]
+      cur[key] = prev ? async (...a: any[]) => { await prev(...a); await h(...a) } : h
+    }
   }
 
   async confirmar(id: string): Promise<PedidoDTO> {
@@ -149,7 +157,54 @@ export function conectarPedidoCompleto(ctx: ConnectorContext): void {
 
 ---
 
-## 7. EVENTBUS (alternativa para eventos broadcast)
+## 7. SOCKETS DENTRO VS FUERA DE TRANSACCIÓN
+
+Este es el error más silencioso del patrón sockets. **Hay dos tipos de socket calls:**
+
+### Dentro de `transactor.run()` — SOLO lógica DB crítica
+
+```ts
+// citas/service.ts
+await this.transactor.run(async () => {
+  cita = await this.repo.create({ ... })
+  await this.sockets.onCitaCreada?.(cita)  // ← SOLO ops DB que deben revertirse si fallan
+})
+```
+
+Reglas:
+- El handler DEBE poder fallar y revertir la transacción completa
+- NO hacer llamadas HTTP (WhatsApp, email) — si el HTTP falla, la transacción falla pero el booking ya ocurrió en la DB
+- Solo poner lógica que tenga sentido dentro de una transacción (ej: reservar un slot)
+
+### Post-commit — notificaciones y side effects
+
+```ts
+// Después del transactor — la cita ya existe, no se puede revertir
+await this.sockets.onCitaCreadaCommitted?.(cita)  // WhatsApp, email, CRM, etc.
+```
+
+Reglas:
+- Si el handler falla, NO revierte la transacción (ya committeó)
+- Ideal para notificaciones, actualizaciones de otros sistemas
+- Puede hacer HTTP, enviar mensajes, actualizar servicios externos
+
+### Convención de nombres
+
+```ts
+// sockets.ts — separar explícitamente por contexto de ejecución
+export interface MiModuloSockets {
+  // Corre DENTRO de transactor.run() — para lógica DB crítica
+  onItemCreado?: (item: ItemDTO) => Promise<void>
+  // Corre DESPUÉS del commit — para notificaciones y side effects
+  onItemCreadoCommitted?: (item: ItemDTO) => Promise<void>
+}
+```
+
+**Regla crítica:** si un socket dispara una llamada HTTP (WhatsApp, email, push notification), DEBE ser un evento `*Committed` post-transacción.
+
+---
+
+## 8. EVENTBUS (alternativa para eventos broadcast)
 
 Cuando muchos módulos necesitan reaccionar al mismo evento sin conocerse entre sí:
 
@@ -253,7 +308,8 @@ test('confirmar pedido funciona sin sockets registrados', async () => {
 
 - [ ] Solo importa tipos (no implementaciones) desde `index.ts` de módulos
 - [ ] Sin `if`, `for`, ni lógica de negocio — solo llamadas de delegación
-- [ ] El service emisor implementa `setSockets()` con MERGE (`{...this.sockets, ...s}`) — no replace
+- [ ] `setSockets()` usa el patrón ACUMULATIVO (for loop + chaining) — NUNCA `{ ...this.sockets, ...s }`
+- [ ] Sockets con HTTP/WhatsApp/email usan eventos `*Committed` — nunca dentro de `transactor.run()`
 - [ ] `setSockets()` usa `?.` al llamar los hooks (son opcionales)
 - [ ] Registrado en composition-root DESPUÉS de los módulos
 - [ ] El módulo funciona correctamente sin el conector (sockets son opcionales)