active-svelte/docs/NEXT_STEPS.md

# Next Steps

Estado al cierre:

- Gate completo verde: `npm run test:all` -> `check` + `test` + `build` + `test:static` + `test:bundle`.
- Suite unitaria verde: `npm test` -> 108 archivos, 1208 tests.
- Typecheck verde: `npm run check` -> 0 errores, 0 warnings.
- Build estatico verde: `npm run build`.
- Static smoke verde: `npm run test:static` -> 6 assets/rutas generadas verificadas.
- Bundle smoke verde: `npm run test:bundle` -> `createActiveApp({})` en 65.30 KB gzip, limite por defecto 70 KB via `ACTIVE_BUNDLE_GZIP_LIMIT_KB`.
- `fmts` verde: `npx vitest run src/arts/fmts` -> 14 archivos, 39 tests.
- `conn` verde: `npx vitest run src/arts/conn` -> 5 archivos, 28 tests.
- `auth` verde: `npx vitest run src/arts/auth src/svrs/auth src/libs/auth` -> 4 archivos, 14 tests.
- Refactor tecnico posterior:
  - `svrs/auth/engine-auth.ts` ya delega CSRF en `csrf-flow.ts`, coherente con password/session/recovery/device flows.
  - `svrs/auth/handlers.ts` delega helpers HTTP/CSRF/error-safe en `handler-runtime.ts`; conserva solo rutas y delegacion al engine.
  - `arts/aapp/active-app.svelte.ts` delega invalidacion Auth -> Permissions/Cache en `integrations/auth-cache.ts`.
  - `libs/cach/engine.ts` centraliza eventos de lectura con `emitForContext(...)`.
  - `arts/conn/connection.ts` usa `createConnectionIdFactory(...)` desde helpers.
  - `arts/conn/connection.ts` delega auth/request/ACK request-reply en `connection-requests.ts`.
  - `svrs/auth/adapters/memory-store.ts` queda como composition root de 39 lineas; la logica se reparte en stores internos de credentials, flows, linked accounts, sessions/devices, refresh y state/snapshot.
  - `arts/perm/client.ts` delega transporte HTTP/JSON en `client-http.ts`; el cliente queda centrado en cache, snapshot y fallback.
  - `arts/perm/client.ts` delega TTL, cache positiva, backoff de fallos e invalidacion por prefijo en `client-cache.ts`.
  - `arts/http/engine-http.ts` delega ejecucion de cada intento, hooks pre-request y diagnosticos request/network en `request-attempt.ts`.
  - `arts/timr/engine-timers.ts` delega `TimerHandle` cancel/reschedule en `timer-handle.ts`.
  - `arts/stor/engine-storage.ts` delega IDs de adapter, bus keys y suscripciones cross-tab en `adapter-registry.ts`.
  - `arts/stor/engine-storage.ts` delega el registro de defaults conflictivos en `defaults-registry.ts`.
  - `libs/cach/engine.ts` delega creacion/escritura/fetch-store de envelopes en `runtime-io.ts`.
  - `libs/cach/engine.ts` delega safe-delete y clear en `runtime-delete.ts`.
  - `arts/sess/engine-session.ts` delega la clasificacion `none/anonymous/identified` en `session-identity.ts`.
  - `arts/sess/engine-session.ts` delega snapshot, generation, dispatch, persistencia y commits en `session-state.ts`.
  - `arts/sess/engine-session.ts` delega la resolucion de revoke local/global/degradado en `session-revoke.ts`.
  - `arts/sess/engine-session.ts` delega refresh, stale-generation, validacion y diagnosticos de refresh en `session-refresh.ts`.
  - `arts/perm/client.ts` delega claves/scope de cache en `client-keys.ts` y lectura de snapshot en `client-snapshot.ts`.
  - `arts/stor/engine-storage.ts` delega lectura/escritura/validacion/migracion de entradas en `entry-runtime.ts`.
  - `arts/stor/entry-runtime.ts` delega defaults, serializer, validate y merge-defaults en `entry-values.ts`.
  - `arts/timr/engine-timers.ts` delega armado nativo, ejecucion, finalizacion e intervalos en `timer-runner.ts`.
  - `arts/cach/active-cache.svelte.ts` delega la entry reactiva en `active-cache-entry.svelte.ts` y normalizacion de errores en helper compartido.
  - `arts/auth/active-auth.svelte.ts` delega CSRF, POST autenticados, validacion de respuestas, normalizacion de errores e invalidacion de cache en `active-auth-runtime.ts`.
  - `arts/conn/connection.ts` delega apertura/cierre logico e `isConnected` en `connection-lifecycle.ts`.
  - `arts/conn/connection.ts` delega la programacion de reconnect y exhaustion en `connection-reconnect-runtime.ts`.
  - `libs/perm/evaluator.ts` delega helpers puros de resultado, dependencias, cadenas logicas y comparacion en `evaluator-helpers.ts`.
  - `arts/http/engine-http.ts` delega la validacion preflight de `bodySchema` en `request-validation.ts`.
  - `arts/http/engine-http.ts` delega la resolucion final de response/error en `response-resolution.ts`.
  - `arts/sium/core/pipe.ts` queda centrado en composicion; factories `refine/transform/codec/meta` viven en `steps.ts`.
  - `libs/cach/engine.ts` delega lectura `get()` en `runtime-get.ts`.
  - `libs/cach/engine.ts` delega escritura `set()` en `runtime-set.ts`.
  - `libs/cach/engine.ts` delega `query()` en `runtime-query.ts`; conserva composition root para context/io/delete/invalidate/mutate/explain.
  - `arts/sium/engine-sium.ts` delega resolucion Lang/fallback e issues en `engine-resolver.ts`.
  - `arts/sium/engine-sium.ts` delega wrappers `validate/validateSync` y diagnostico de validacion en `engine-validation.ts`.
  - `arts/conn/connection.ts` delega decode/routing de frames entrantes en `connection-message-router.ts`.
  - `arts/conn/connection.ts` delega el intento open/auth/flush/join en `connection-connect.ts`.
  - `arts/conn/connection.ts` delega current transport, attach/detach y close en `connection-transport-runtime.ts`.
  - `arts/conn/connection.ts` delega cierre intencional y close-event handling en `connection-close.ts`.
  - `arts/conn/connection.ts` delega disposed/reuse/singleflight de connect en `connection-connect-controller.ts`.
  - `arts/timr/engine-timers.ts` delega fan-out de listeners y diagnostico de listeners en `timer-events.ts`.
  - `arts/timr/engine-timers.ts` delega la construccion de entradas internas en `timer-entry.ts`.
  - `arts/timr/engine-timers.ts` delega cancelacion y seleccion por scope en `timer-cancel.ts`.
  - `arts/timr/engine-timers.ts` delega entrada viva, contexto de task y max-runs en `timer-entry.ts`.
  - `libs/color/segments.ts` reutiliza helpers locales para canales requeridos y parsing por rango RGB/HSL.
  - `libs/days/segments.ts` centraliza el formateo de hora 12h y mantiene imports agrupados.
- Integracion total ampliada: `Auth.signOut()` valida anonimizacion, invalidacion de `Permissions` y evento `Cache.invalidate`.
- Tanda focalizada verde: `npx vitest run src/arts/conn src/libs/cach src/arts/cach src/svrs/cach src/arts/auth src/svrs/auth src/libs/auth src/arts/aapp/test/ecosystem.integration.test.ts` -> 19 archivos, 82 tests.
- `/test/ecosystem` revisado en navegador: carga sin errores de consola, `ar` cambia a `rtl`, Formats se actualiza por locale, Perm cambia con rol `viewer`, Cach re-scopea por locale y Conn loopback publica/recibe.
- `src/arts/aapp/test/ecosystem.integration.test.ts` ampliado para cubrir rol `viewer` no-allow y cache re-scoped por locale.
- Referencias residuales de marca anterior eliminadas de `src/` fuera de rutas temporales: docs, páginas de test y constantes de cookies/headers auth usan ahora `Active/active`.
- `src/arts/conn/README.md` ampliado: contrato de raíz/conexión/canal, estados, transportes, request/reply, reconnect, heartbeat, sesión, diagnostics/logger, errores y testing.
- `src/arts/fmts/README.md` ampliado con guia de uso, `LocaleSource`, contrato auto/manual, submodulos, listeners, integracion con `aapp` y tests.
- `fmts` redujo boilerplate activo con helpers `readFrom` / `writeTo` y los engines comparten directamente las funciones de `createFormatsLocaleState`; APIs públicas sin cambios.
- `src/web/routes/temp/` corregido: scripts tipados, warnings Svelte eliminados y compatible con `npm run check`.
- `aapp` integration reforzado: `Connections` creadas antes de `Sess` reciben eventos posteriores de sesion y cierran en revoke.
- `aapp` composition reforzado: `Frontend.dir` reacciona a locale solo mientras esta en `auto`; los overrides manuales no se pisan.
- `src/arts/fend/README.md` ampliado: API, composicion via App, contrato auto/manual, locale/dir, salida DOM, integracion `adom`, persistencia, SSR y tests.
- `src/arts/logr/README.md` aclara contrato comun `Logger` en `$libs/logr` y `Diagnostics` como capa catalogada encima del logger, sin mini-loggers por modulo.
- Checklist `before_0_1.md` alineada con el estado real: CI sin lint global de momento, `test:all` como gate de release, presupuesto de bundle en 70 KB gzip y docs de versionado/public surface.
- Nuevo smoke estatico `scripts/static-smoke.mjs` integrado en CI y `test:all`; verifica landing docs, instalacion, AI agents, security, `/test/ecosystem` y manifest.
- Docs de `/active/get-started/installation`, `/versioning` y `/ai-agents` actualizadas con vocabulario de gates (`check`, `test`, `build`, `test:static`, `test:bundle`, `test:all`).
- Tests de superficie pública en `src/arts/aapp/test/active-app.test.ts` cubren roots always-present y factorias scoped.
- Tests de `perm` cubren stale `batch()` y `what()` tras cambio de actor/snapshot.
- `svrs/perm` tiene contrato DB operativo: `loadActivePermissionPolicies`, `createPermissionDatabaseProviders`, repositorios tipados para políticas/relaciones, tests focales y SQL PostgreSQL reforzado con target generated columns, índice por target, unique active-version y check de effect en audit.
- Docs de `svrs/perm` y `/active/docs/perm` explican tablas, lifecycle de políticas, provider de relaciones, tenant resolution, wiring server y audit de decisiones.
- `svrs/cach/README.md` creado: documenta boundary server/client, API de `EngineCache`, scopes seguros, policies, invalidacion por epochs, integracion auth/sess/perm, contrato de adapters, observabilidad, seguridad y tests.
- `svrs/auth` tiene SQL PostgreSQL de referencia en `src/svrs/auth/sql/postgres.sql` y README ampliado con mapping `AuthRepository`, tablas, reglas de produccion, refresh rotation con locks y limpieza periodica.
- `/active/docs/auth` y `/active/docs/cach` reflejan ahora las piezas server: persistencia DB de auth, tablas de referencia, `createDbAuthAdapter`, boundary cache server/client y modelos de adapter.
- `before_0_1.md` alineado con evidencias actuales: S1/S2/S3/S4/S5/S6/S7 y A1/A2/A3/A4/A5 quedan cerrados; `SECURITY.md` cubre cookie scopes, CSRF, refresh rotation, OAuth state/PKCE, MFA actual y actor/tenant model.
- `before_0_1.md` tambien marca como cerrados repo hygiene, build/tooling y assets de marca segun ficheros reales (`README`, `SECURITY`, `CONTRIBUTING`, `CHANGELOG`, `.github`, `static/*`, `app.html`).
- `.gitignore` evita que estado local de `.claude/`, `.opencode/` y `.idea/vcs.xml` entre accidentalmente en commits.
- Memory adapters de auth/cache emiten warning productivo deduplicado; los harness de test lo suprimen donde corresponde.
- `cach` expone `defaultMemoryAdapter` para configurar solo el adapter memory implícito cuando no se pasa `adapter`; las rutas `/test/aapp`, `/test/cach`, `/test/conn`, `/test/ecosystem` y `/test/perm` lo usan para silenciar el warning productivo de forma explícita en demos/prerender sin apagarlo para apps reales.
- Validación focal posterior al ajuste de `cach`: `npm run check`, `npx vitest run src/libs/cach src/svrs/cach src/arts/cach src/arts/aapp/test/active-app.test.ts`, `npm run build` y `npm run test:static` verdes.
- Documentación de `buss` corregida para reflejar el código real: `App.Bus` central, contratos en `$libs/buss`, engine en `$buss`, eventos públicos vía `publishApp*`/`onApp*`, `BusEnvelope` real (`at`, no CloudEvents puro) y sin sección obsoleta de gaps ya implementados.
- Tests de `aapp`/`conn` normalizados para publicar `APP_EVENT_USER_IDENTITY_CHANGED` mediante `publishAppUserIdentityChanged(...)`, de modo que la suite ejercita las mismas guardas de runtime/payload que la app.
- Validación focal posterior al ajuste de `buss`: `npx vitest run src/arts/buss/test/engine-bus.test.ts src/libs/aapp/test/events.test.ts src/arts/aapp/test/active-app.test.ts src/arts/aapp/test/session-translator.test.ts src/arts/aapp/test/ecosystem.integration.test.ts src/arts/conn/test/connection.test.ts` -> 6 archivos, 74 tests verdes; `npm run check` verde.
- Integración total ampliada con un caso `permissionsRefresh + tenantSwitched + locale` mientras una conexión de chat sigue abierta: `permissionsRefresh` invalida solo Permissions, `tenantSwitched` limpia Permissions + Cache sin reautenticar el socket, y el cambio de locale re-scopea Cache/Formats/Frontend sin reauth.
- Integración total ampliada con un caso de webhook/realtime de permisos: `conn` recibe `permissions.changed`, la app publica `APP_EVENT_PERMISSIONS_REFRESH_REQUESTED` mediante helper seguro, `Permissions` invalida por opt-in, descarta respuestas stale en vuelo y `Cache`/`Connections` no hacen side-effects destructivos.
- Integración total ampliada con un caso de revocación remota de sesión por realtime: `conn` recibe `session.revoked`, la app revoca `Sess`, `aapp` publica cambio de identidad, `Permissions`/`Cache` limpian estado identity-scoped y el chat queda cerrado sin reutilizar credenciales.
- Validación focal posterior al nuevo caso compuesto: `npx vitest run src/arts/aapp/test/ecosystem.integration.test.ts` -> 9 tests verdes; `npx vitest run src/arts/aapp/test/ecosystem.integration.test.ts src/arts/aapp/test/active-app.test.ts src/arts/buss/test/engine-bus.test.ts src/libs/aapp/test/events.test.ts src/arts/conn/test/connection.test.ts src/arts/cach src/arts/perm` -> 7 archivos, 90 tests verdes; `npm run check` verde.
- No commitear `.idea/`, `.claude/` ni `.opencode/`.
- No commitear ni tocar `src/web/routes/temp/` salvo peticion explicita; hay cambios locales en `temp/c2` que quedan fuera del commit de cierre.

Pendiente para manana:

- Revisar documentacion restante de todos los modulos con ojo de consumidor externo: API real, factories, metodos, opciones, errores, ejemplos, dinamicas auto/manual y errores comunes.
- Prioridad especial siguiente: decidir si los SQL de referencia de `auth`/`perm` son cierre suficiente para `0.1` o si hace falta un adapter ejecutable para un ORM concreto.
- Continuar la reduccion de archivos grandes: prioridad `conn/connection.ts`, `svrs/auth/engine-auth.ts`, helpers de `cach` y piezas repetidas en docs/test harness.
- Ampliar tests de integracion cruzada: `auth + sess + perm + cach + http + stor + fmts + conn + timr + logr`, incluyendo login/logout, cambio de actor, invalidacion cache, cambio locale, permisos y reconnect.
- Revisar la adopcion final del contrato comun `Logger` / diagnostics en todos los modulos, sin acoplar artefactos a `arts/logr`; primera pasada limpia salvo `aapp` como composition root, `arts/logr` y tests.
- Mantener `npm run test:all` como gate regular antes de commits grandes; `npm run lint` sigue siendo deuda global separada, no meter nueva deuda en archivos tocados.