active-svelte/audit-codex.md

# Auditoria Codex - ecosistema Active + Orca

Fecha: 2026-05-04
Workspace: `G:\dev\svelte\active`

## Alcance

Se audito el estado actual del ecosistema con foco en el nuevo modulo
`src/arts/orca` y sus puntos de acoplamiento con:

- `src/arts/active-app`
- `src/arts/bus`
- `src/arts/session`
- `src/arts/cache`
- `src/arts/perm`
- `src/arts/connection`
- documentacion publica en `src/arts/*/README.md` y pagina activa generada.

No se modifico codigo existente. El arbol ya tenia cambios previos en:

- `src/arts/orca/consts.ts`
- `src/arts/orca/result.ts`
- `src/arts/orca/types.ts`

Esos cambios parecen corregir parte de la deriva de comentarios `v0.1+` respecto a
timeout/fatal/gates/compensation, pero no cierran todos los problemas.

## Veredicto

`orca` esta bien orientado arquitectonicamente. La decision fuerte, y la que
realmente eleva el ecosistema, es mover las reacciones inter-modulo a una capa de
orquestacion declarativa situada en `active-app`, no dentro de `cache`, `perm`,
`session` o `connection`. Eso reduce acoplamiento y permite testear flujos
compuestos como objetos de ejecucion (`OrcaRunResult`).

El modulo, sin embargo, ya ha crecido mas rapido que su contrato. El motor actual
implementa gates, timeouts de accion, compensacion, transacciones, payloads en
tokens, fan-in y politicas de cola. La documentacion mezcla tres versiones a la
vez: boceto conceptual, v0 inicial y estado real. Antes de seguir expandiendo
`orca`, conviene congelar el contrato real y eliminar ambiguedades.

Estado de pruebas focalizadas:

```txt
npx vitest run src/arts/orca/test src/arts/active-app/test/presets.test.ts

Test Files  4 passed
Tests       169 passed
```

## Hallazgos P1

### 1. Liberacion de trace no es segura con runs paralelos

Referencia:

- `src/arts/orca/engine-orca.ts:928`
- `src/arts/orca/engine-orca.ts:931`
- `src/arts/orca/engine-orca.ts:935`

`maybeReleaseTrace()` borra `traceStates` si no quedan eventos en cola. El propio
comentario reconoce que no sabe si hay runs en vuelo del mismo trace. Eso era
defendible con ejecucion estrictamente secuencial, pero ya existe
`ORCA_QUEUE_PARALLEL`. Si dos eventos derivados del mismo trace corren en
paralelo, el primero que termine puede borrar el estado de trace mientras el otro
sigue vivo.

Impacto:

- Los contadores `maxDepth`, `maxEventsPerTrace`, `repeatedEventLimit` y
  `dedupeKey` pueden resetearse antes de tiempo.
- Un loop por eventos derivados puede saltarse la proteccion si el trace se borra
  mientras quedan runs paralelos activos.
- La trazabilidad de un flujo enterprise deja de ser confiable justo en el modo
  mas peligroso: paralelo.

Recomendacion:

- Mantener `traceInFlightCount` por `traceId`.
- Incrementarlo en `spawnRun()`.
- Decrementarlo en el `finally` de `executeRun()`.
- Liberar el trace solo cuando `queuedCount(traceId) === 0` e
  `inFlightCount(traceId) === 0`.
- Anadir test: dos eventos derivados con `ORCA_QUEUE_PARALLEL` en el mismo trace;
  el primero termina, el segundo emite otro evento repetido y el guard sigue
  aplicando.

### 2. `provides` no limita `emits`, asi que la validacion puede mentir

Referencia:

- `src/arts/orca/types.ts:421`
- `src/arts/orca/types.ts:424`
- `src/arts/orca/types.ts:425`
- `src/arts/orca/engine-orca.ts:1117`
- `src/arts/orca/engine-orca.ts:1124`

El contrato dice que `provides` es lo que una accion puede producir, y
`validate()` usa `provides` para detectar tokens imposibles. Pero el runtime
acepta cualquier token que venga en `result.emits`, aunque no este declarado en
`provides`.

Impacto:

- `validate()` no es una garantia fuerte; es una estimacion basada en intencion.
- Una accion puede desbloquear otra con un token que el grafo no declaraba.
- Un typo en `emits` puede cambiar el pipeline sin que `validate()` lo vea.
- El futuro `setupOrca()` tipado pierde parte de su sentido si el runtime permite
  emisiones fuera de esquema.

Recomendacion:

- En modo dev, lanzar o registrar `CONFIGURATION_INVALID` cuando una accion emite
  un token no declarado en `provides`.
- En modo prod, al menos registrar diagnostic `orca.configuration.invalid` o
  descartar el token no declarado segun opcion.
- Documentar excepcion solo si se decide permitir tokens dinamicos, pero entonces
  `validate()` debe llamarse "best effort", no "static graph validation".

### 3. `ORCA_QUEUE_REPLACE` no es `replace-current`, solo reemplaza queued

Referencia:

- `src/arts/orca/consts.ts:73`
- `src/arts/orca/engine-orca.ts:420`
- `src/arts/orca/engine-orca.ts:421`
- `src/arts/orca/engine-orca.ts:422`
- `src/arts/orca/README.md:439`
- `src/arts/orca/README.md:1444`

Hay dos semanticas distintas usando el mismo nombre mental:

- Una seccion del README describe `replace` como "aborta el run activo y empieza
  uno nuevo", estilo `takeLatest`.
- El motor implementa "reemplaza solo entradas queued; no aborta in-flight".
- Otra seccion posterior del README ya reconoce esta realidad.

Impacto:

- Para formularios, busquedas, navegacion o cambio de identidad, un usuario puede
  esperar "ultima intencion gana", pero el run anterior seguira ejecutandose.
- Si la accion vieja muta cache/conexiones despues de la nueva, puede pisar estado.
- El nombre `replace` es ambiguo para usuarios que vienen de saga/Rx/RTK.

Recomendacion:

- Renombrar la politica actual a algo explicito: `ORCA_QUEUE_REPLACE_QUEUED` o
  `ORCA_QUEUE_LATEST_QUEUED`.
- Reservar `ORCA_QUEUE_REPLACE_CURRENT` / `ORCA_QUEUE_TAKE_LATEST` para la
  variante fuerte que aborta in-flight.
- Si se mantiene el nombre actual, borrar del README cualquier promesa de abortar
  el run activo.

### 4. IDs de run/event/trace usan `Date.now()` y `Math.random()` fuera de `timr`

Referencia:

- `src/arts/orca/engine-orca.ts:1513`
- `src/arts/orca/engine-orca.ts:1514`
- `src/arts/orca/engine-orca.ts:1517`
- `src/arts/orca/engine-orca.ts:1518`
- `src/arts/orca/engine-orca.ts:1521`
- `src/arts/orca/engine-orca.ts:1522`
- `src/arts/orca/README.md:841`

El README establece que `orca` no debe usar `Date.now()` ni `setTimeout()`
directamente. Los timestamps del envelope ya pasan por `timers.clock.now()`, pero
los IDs de run/event/trace no.

Impacto:

- Tests y replay no son plenamente deterministas.
- En SSR/hydration o tests con clocks controlados, los IDs no siguen el tiempo
  simulado.
- La disciplina "todo tiempo via timr" queda rota justo en el modulo que quiere
  ser trazable.

Recomendacion:

- Anadir `idFactory` a `EngineOrcaOptions` o tres factories separadas:
  `runIdFactory`, `eventIdFactory`, `traceIdFactory`.
- Default: contador monotono con prefijo, alimentado por `timers.clock.now()` si
  se quiere incluir tiempo.
- Tests: factory determinista para snapshots.

### 5. `setupOrca()` esta documentado como API recomendada pero no existe

Referencia:

- `src/arts/orca/README.md:235`
- `src/arts/orca/README.md:241`
- `src/arts/orca/README.md:271`
- `src/arts/orca/README.md:284`
- `src/arts/orca/README.md:1271`
- `src/arts/orca/index.ts`

El README recomienda `setupOrca()` para apps grandes y muestra ejemplos, pero no
hay export ni implementacion en `src/arts/orca`.

Impacto:

- La documentacion invita a usar una API inexistente.
- El usuario no sabe si debe usar `App.Orca.onEvent()` directo, presets o un
  setup tipado futuro.
- La promesa de validacion fuerte de tokens/eventos queda sin soporte.

Recomendacion:

- O implementar un `setupOrca()` minimo, aunque solo envuelva `onEvent` con
  declaracion de eventos/tokens/actions.
- O mover esa seccion a "Futuro / v0.1" y dejar claro que v0 real es
  `createEngineOrca()` + `App.Orca.onEvent()`.

### 6. La integracion con `connection` no esta cerrada y la documentacion promete mas de lo que existe

Referencia:

- `src/arts/active-app/presets/standard.ts:28`
- `src/arts/active-app/presets/index.ts:5`
- `src/arts/active-app/service-factories/connections.ts:9`
- `src/arts/connection/README.md:83`
- `src/arts/connection/README.md:93`
- `src/arts/connection/README.md:100`
- `src/arts/connection/session-wiring.ts:27`

`applyStandardOrca()` solo registra presets de cache y perm. No hay preset para
`connections.reauthenticateAll()` ni para `connections.closeAll()` en cambios de
identidad/revoke/expire. A la vez, la documentacion de `connection` habla de
`autoReauthOn: 'standard'` y de escuchar `SESSION_EVENT_IDENTITY_CHANGED`.

Ademas, `defineActiveConnections()` ya no inyecta `bus` ni `session`; el comentario
dice que identidad debe venir por orca preset o por una `session` manual, pero ese
preset no existe.

Impacto:

- Una app que siga la documentacion puede creer que las conexiones se reautentican
  al cambiar de usuario, pero con `applyStandardOrca(App)` no ocurre.
- El caso critico que motivo `orca` ("chat conectado con credenciales del usuario
  anterior") sigue sin preset estandar.
- `connection` conserva un mecanismo interno de `session-wiring` que compite
  conceptualmente con la nueva regla: los artefactos publican/reciben eventos; la
  app orquesta reacciones.

Recomendacion:

- Crear preset en `active-app/presets`:
  `applyConnectionsReauthOnIdentityChange(App)`.
- Definir si el estandar hace `reauthenticateAll()` o `closeAll()` cuando no hay
  credencial nueva.
- Actualizar `applyStandardOrca()` para incluir conexiones cuando `App.connections`
  exista.
- Decidir si `connection.session-wiring` queda como modo local/manual o se depreca
  a favor del preset de `orca`.

## Hallazgos P2

### 7. `runActionWithTimeout()` aborta de forma cooperativa, pero la accion puede seguir mutando estado

Referencia:

- `src/arts/orca/engine-orca.ts:1042`
- `src/arts/orca/engine-orca.ts:1052`
- `src/arts/orca/engine-orca.ts:1056`
- `src/arts/orca/engine-orca.ts:1058`
- `src/arts/orca/engine-orca.ts:1070`

El timeout hace `actionController.abort()` y resuelve `orcaTimeout(timeoutMs)`, pero
la promesa original de la accion sigue viva si la accion no respeta `ctx.signal`.
Esto es normal en JS, pero debe tratarse como contrato de seguridad.

Impacto:

- Una accion timeout puede mutar cache, conexiones o permisos despues de que el run
  ya haya tomado otra decision.
- Los tests pueden pasar porque el resultado es `timeout`, pero el side-effect
  tardio queda fuera del trace.

Recomendacion:

- Documentar que toda accion async debe comprobar `ctx.signal.aborted` antes y
  despues de awaits relevantes.
- Anadir helper `ctx.throwIfAborted()` o `orcaAbortIfSignaled(ctx)`.
- Anadir test: accion con timeout que intenta mutar despues; demostrar que el
  patron recomendado lo evita.

### 8. La cola es global para eventos no-parallel, aunque el contrato se lee como per-event

Referencia:

- `src/arts/orca/engine-orca.ts:526`
- `src/arts/orca/engine-orca.ts:527`
- `src/arts/orca/engine-orca.ts:529`
- `src/arts/orca/engine-orca.ts:531`

`canStartRun()` serializa globalmente todos los eventos no-parallel:
`nonParallelInFlight === 0`. Eso significa que un evento lento de `cache` puede
bloquear un evento no relacionado de `perm`, `connection` o cualquier feature.

Impacto:

- Semantica mas conservadora y lenta de lo que sugiere "queue policy per event".
- Posible cuello de botella en apps grandes con flujos independientes.
- Si esta decision es intencional, falta nombrarla como "single lane".

Recomendacion:

- Decidir explicitamente:
  - Modelo A: serializacion global por defecto, documentada como garantia simple.
  - Modelo B: serializacion por evento, con concurrencia entre eventos distintos.
- Si se mantiene A, renombrar/comentar como `globalSerialLane`.
- Si se pasa a B, usar `inFlightByEvent` para bloquear solo el mismo evento.

### 9. `commit()` congela el grafo; eso choca con features lazy si no se documenta como modo prod

Referencia:

- `src/arts/orca/types.ts:711`
- `src/arts/orca/types.ts:723`
- `src/arts/orca/engine-orca.ts:1275`
- `src/arts/orca/test/engine-orca.test.ts:4013`

El comportamiento actual esta claro en codigo y tests: despues de `commit()`,
`onEvent()` y `configureEvent()` lanzan `OrcaFrozenError`. Esto no es un bug por
si mismo, pero tensiona el objetivo de registrar acciones desde features
lazy-loaded.

Impacto:

- Si una app llama `App.Orca.commit()` durante bootstrap, una ruta lazy ya no puede
  registrar sus acciones al cargar.
- HMR/devtools pueden quedar bloqueados si no se separa "validar" de "sellar".

Recomendacion:

- Documentar `commit()` como opcion production/seal, no como paso obligatorio.
- Considerar `validate()` para dev y `commit()` solo para builds donde el grafo es
  completo al arrancar.
- Si se quiere lazy + freeze, introducir versionado por evento: cada run usa un
  snapshot, pero el registro global puede crecer entre runs.

### 10. `ctx.emit()` es correcto, pero la atribucion via `bus.publish()` depende de AsyncLocalStorage

Referencia:

- `src/arts/orca/engine-orca.ts:133`
- `src/arts/orca/engine-orca.ts:204`
- `src/arts/orca/engine-orca.ts:864`
- `src/arts/orca/als.ts`
- `src/arts/orca/README.md:606`
- `src/arts/orca/README.md:621`
- `src/arts/orca/README.md:1470`

El diseno correcto es claro: modulo -> `bus.publish()`, accion -> `ctx.emit()`.
El motor intenta interceptar `bus.publish()` dentro de acciones mediante
AsyncLocalStorage cuando esta disponible. En navegador puede no estar disponible,
por lo que el mismo `bus.publish()` dentro de una accion puede ser hijo en Node y
root event en browser.

Impacto:

- Trazas distintas entre SSR/tests Node y browser.
- Reentry guards no aplican igual si un evento derivado sale como root.

Recomendacion:

- Mantener la regla dura: las acciones usan `ctx.emit()` siempre.
- Tratar la interceptacion ALS como bonus diagnostico, no como contrato.
- Anadir lint/documentacion: no usar `App.Bus.publish()` dentro de una accion de
  `orca` salvo que se quiera crear root event explicito.

### 11. `engine-orca.ts` ya es un monolito de responsabilidades

Referencia:

- `src/arts/orca/engine-orca.ts` (~58 KB)

El engine concentra registro, cola, trace state, reentry, ejecucion de waves,
timeouts, compensation, validation, ID generation, diagnostics y public API.

Impacto:

- Dificulta revisar invariantes delicadas como "trace cleanup + parallel".
- Hace mas probable que futuras features (`runTimeoutMs`, `setupOrca`, inspector)
  entren sin frontera clara.
- Ya contradice la direccion del ecosistema de reducir monolitos (`connection.ts`
  se venia refactorizando por el mismo motivo).

Recomendacion de split:

- `queue.ts`: enqueue, policies, drain, in-flight counters.
- `trace.ts`: envelope, trace state, reentry guards, release.
- `runner.ts`: stages, waves, action execution, status precedence.
- `timeouts.ts`: action timeout helpers y timer keys.
- `compensation.ts`: LIFO compensation / transaction compensation.
- `validation.ts`: validate/commit helpers.
- `ids.ts`: factories deterministas.
- `engine-orca.ts`: composicion publica.

### 12. Los presets usan action ids y tokens inline/locales

Referencia:

- `src/arts/active-app/presets/cache-clear-on-identity-change.ts:6`
- `src/arts/active-app/presets/cache-clear-on-identity-change.ts:7`
- `src/arts/active-app/presets/cache-clear-on-revoke.ts:6`
- `src/arts/active-app/presets/cache-clear-on-revoke.ts:7`
- `src/arts/active-app/presets/perm-invalidate-on-identity-change.ts:6`
- `src/arts/active-app/presets/perm-invalidate-on-identity-change.ts:7`

Los eventos del ecosistema ya estan centralizados como constantes, pero los
`ACTION_ID` y `TOKEN_*` de presets quedan como strings locales no exportados.

Impacto:

- No se pueden reutilizar en tests de integracion, docs, inspector `/test/orca`
  o setup tipado.
- Rompe la regla emergente: "eventos, tokens y action ids como constantes".
- El inspector no puede mostrar nombres canonicos importables.

Recomendacion:

- Crear `src/arts/active-app/presets/consts.ts` o exportar desde cada preset:
  `APP_ORCA_ACTION_CACHE_CLEAR_ON_IDENTITY_CHANGE`,
  `APP_ORCA_TOKEN_CACHE_CLEARED_ON_IDENTITY_CHANGE`, etc.
- Usar nombres de constantes en README y pagina docs.

## Hallazgos P3

### 13. Header de `engine-orca.ts` esta obsoleto

Referencia:

- `src/arts/orca/engine-orca.ts:24`
- `src/arts/orca/engine-orca.ts:25`
- `src/arts/orca/engine-orca.ts:26`

El comentario inicial dice que `after`, `unless`, `abortOn`,
`actionTimeoutMs` y `compensate` se aceptan pero se ignoran. El motor ya los
implementa.

Impacto:

- La siguiente persona que lea el archivo empieza con un mapa mental falso.
- Ya se corrigieron comentarios en `types.ts`, `consts.ts` y `result.ts`, pero el
  comentario mas importante del motor sigue atrasado.

Recomendacion:

- Actualizar el bloque de cabecera para describir el estado real.
- Evitar version tags contradictorios dentro del codigo; mover roadmap al README.

### 14. El README de `orca` mezcla contrato actual, boceto y roadmap en un solo flujo

Referencia:

- `src/arts/orca/README.md:511`
- `src/arts/orca/README.md:1411`
- `src/arts/orca/README.md:1506`
- `src/arts/orca/README.md:1522`

Ejemplo claro: una seccion dice que en v0 los tokens son flags sin payload; otra
seccion posterior dice que los tokens con payload ya estan implementados. Esto no
es solo estetico: afecta al modo en que un desarrollador modela acciones.

Impacto:

- La documentacion no sirve como contrato normativo.
- Los lectores no saben si estan viendo la version deseada o la version real.

Recomendacion:

- Reestructurar README en tres bloques cerrados:
  - "Contrato actual implementado"
  - "Patrones recomendados"
  - "Roadmap / no implementado"
- Eliminar del contrato actual cualquier API no exportada (`setupOrca`) o moverla
  a roadmap.
- Mantener una tabla "Feature -> estado -> archivo/test".

### 15. Falta una prueba compuesta del caso que motivo `orca`: cambio de usuario con cache/perm/connection

Referencias:

- `src/arts/active-app/test/presets.test.ts`
- `src/arts/orca/test/engine-orca.test.ts`

Hay buena cobertura unitaria de `orca` y presets basicos. Falta el escenario
ecosistema que debe probar el valor real:

1. Usuario A abre sesion.
2. Chat/conexion usa credencial A.
3. Cache actor-scoped guarda datos de A.
4. Perm calcula snapshot de A.
5. Cambia a usuario B.
6. Orca ejecuta clear cache, invalidate perm y reauth/close connection.
7. Ningun dato/credencial de A queda observable.

Impacto:

- El sistema puede estar correcto por modulo pero fallar justo en composicion.
- El caso "chat con credenciales antiguas" sigue sin prueba de regresion.

Recomendacion:

- Crear test de integracion en `src/arts/active-app/test/ecosystem-orca.test.ts`
  o equivalente.
- Usar fakes de cache/perm/connection con counters y credenciales capturadas.
- Verificar orden por `OrcaRunResult`: cache -> perm -> connection si se decide
  dependencia via tokens.

## Observaciones positivas

- `App.Bus`, `App.Timers` y `App.Orca` ya son core siempre presentes en
  `createActiveApp()`, y `Orca` es inerte hasta registrar acciones. Esa decision
  encaja con el diseno enterprise sin obligar a cada app a crear singletons
  manuales.
- Los presets viven en `active-app/presets`, no dentro de los artefactos. Esto es
  correcto: `cache` no debe conocer `session`; `perm` no debe conocer `auth`;
  `orca` no debe conocer modulos.
- `ActiveOrca` es un wrapper fino y razonable: estado reactivo, sin meter logica
  del engine en Svelte.
- La suite focalizada de `orca` ya es grande: 169 tests entre engine/active/result
  y presets. Para un modulo recien nacido, eso es muy buena base.
- `ctx.signal` existe en `OrcaActionContext`; eso habilita cancelacion cooperativa
  y es la direccion correcta.

## Recomendacion de orden de trabajo

1. Corregir P1.1: trace cleanup con runs paralelos.
2. Cerrar P1.2: `provides` debe ser contrato real o `validate()` debe declararse
   best-effort.
3. Resolver P1.3: renombrar/split de `replace` para evitar semantica ambigua.
4. Sustituir `Date.now()`/`Math.random()` por factories deterministas.
5. Decidir `setupOrca()`: implementarlo minimo o moverlo fuera de v0.
6. Crear preset de `connection` y test compuesto usuario A -> usuario B.
7. Reordenar README para separar implementado/recomendado/roadmap.
8. Refactorizar `engine-orca.ts` por responsabilidades antes de anadir run/stage
   timeout, inspector visual o setup tipado.

## Conclusion

`orca` merece seguir. No es "otro bus": es el sitio correcto para convertir
flujos inter-modulo en artefactos trazables y testeables. Pero precisamente por
eso no puede permitirse ambiguedad en nombres, timeouts, tokens y concurrencia.

El ecosistema esta cruzando una frontera importante: de librerias coherentes a
runtime de aplicacion. La prioridad ahora no es meter mas features, sino hacer
que el contrato de `orca` sea tan fiable como su idea.