Manual de administración

Guía operativa para administradores: configurar modelos LLM, autorar casos de uso, gestionar equipos y permisos. Mezcla pasos de UI con cambios en código (YAML / .md / .env) cuando la UI todavía no cubre el caso.

Modelos LLM — visión general

La plataforma usa un sistema de cadenas de modelos: cada caso de uso declara una lista ordenada de modelos preferidos. En tiempo de ejecución la cadena se resuelve aplicando filtros (permisos del usuario + claves API configuradas), y un wrapper resiliente (ResilientProvider) la recorre saltando al siguiente modelo si el actual falla con un error transitorio (HTTP 429/503/504, timeout, proveedor sin clave).

La resolución sigue este orden de capas, la primera que coincide gana (no se acumulan):

1. model_chain_by_phase[phase] — override por fase (extracción, razonamiento, drafting, validación). Hoy el bucle del agente no emite fronteras de fase, así que esta capa está reservada para uso futuro.
2. model_chain_by_tool[tool_name] — override por herramienta. Reservado: las herramientas del agente actuales no invocan al LLM por su cuenta.
3. model_chain del caso de uso — la cadena base.

Después se concatena la cadena global de fallback (siempre presente). Esto resuelve el caso "el caso de uso pide modelos que no están configurados → caer al fallback general".

Proveedores y claves API código

Las claves se guardan en .env en la raíz del repo y se inyectan al contenedor vía docker-compose.yml. Variables soportadas:

Las claves viven como secretos de Google Secret Manager en el proyecto GCP (kebab-case: claude-api-key, deepseek-api-key, etc.) y se montan al servicio Cloud Run vía --set-secrets. El comando ./deploy.sh secrets sync sincroniza el .env.deploy local al Secret Manager (idempotente: crea versión nueva por cada secret que difiere; el SA tiene roles/secretmanager.secretAccessor). Proveedores soportados:

Gemini ya NO usa API key: la migración a Vertex AI (commit e13ca71) reemplazó LEGAL_AI_GEMINI_API_KEY por autenticación ADC. La disponibilidad del provider Gemini se gate por LEGAL_AI_GOOGLE_CLOUD_PROJECT (env var no-secret).

Si una variable no está seteada, su proveedor queda no disponible: cualquier modelo de ese proveedor que aparezca en una cadena se filtra automáticamente al resolver. Si la clave existe pero el modelo falla en runtime, ResilientProvider registra un evento llm_chain_hop en los logs y salta al siguiente modelo.

Por qué las claves no se editan desde la UI

Decisión explícita de diseño: las claves API viven solo en variables de entorno (cargadas por Settings al boot vía pydantic-settings). No hay endpoint PUT /api/admin/api-keys, ni columna api_key en ninguna tabla. Para cambiar una clave: editar .env y reiniciar la app.

Permitir edición desde UI obligaría a persistirlas en DB (no hay otra forma de modificarlas en runtime sin restart). Eso introduce trade-offs concretos:

El balance hoy se inclina al modelo env-only por tres razones acumulativas:

1. La app es single-tenant — no necesita una clave por cliente. Si el roadmap pasa a SaaS multi-tenant, esa razón cae y vale revisar.
2. La rotación es infrecuente — pasa cuando rota una API key (raro), no es flujo diario que valga UI dedicada.
3. El costo de hacerlo bien es alto — encriptación en reposo, KMS, audit log de cambios, validación al guardar. Más trabajo del que ahorra hasta tener un volumen real de operación.

Si en algún momento se decide migrar a DB-editables, la implementación correcta debería incluir: encriptación con clave en KMS, audit log inmutable, validación round-trip al guardar, fallback automático a env si la fila DB está ausente, y mecanismo de rollback. No es trivial.

El manifiesto de modelos código

Fuente única de verdad: src/permissions/llm_models_manifest.yaml. Define qué modelos existen, a qué proveedor pertenecen, en qué tier están y cuál es su sustituto inmediato. Cualquier modelo no registrado aquí no se puede referenciar en las cadenas.

items:
  - id: claude-opus-4-7
    provider: anthropic
    label: "Claude Opus 4.7"
    category: "Anthropic"
    tier: high
    next: claude-sonnet-4-6
  - id: gemini-2.5-flash
    provider: google
    label: "Gemini 2.5 Flash"
    category: "Google"
    tier: mid
    next: gemini-2.5-flash-lite
  - id: gemini-2.5-flash-lite
    provider: google
    label: "Gemini 2.5 Flash Lite"
    category: "Google"
    tier: low
    next: null
  - id: deepseek-v4-flash
    provider: deepseek
    label: "DeepSeek V4 Flash"
    category: "DeepSeek"
    tier: low
    next: gemini-2.5-flash

tiers:
  high: [claude-opus-4-7, gemini-2.5-pro, gpt-5, deepseek-v4-pro]
  mid:  [claude-sonnet-4-6, gemini-2.5-flash, gpt-5-mini]
  low:  [claude-haiku-4-5, gemini-2.5-flash-lite, gpt-5-nano, deepseek-v4-flash]

global_fallback_chain:
  - gemini-2.5-flash-lite   # validado para chat común y análisis estándar
  - gemini-2.5-flash        # hop cuando lite rebota o caso pide más
  - deepseek-v4-flash       # salvavidas cross-vendor

Agregar un modelo nuevo

1. Editar src/permissions/llm_models_manifest.yaml y agregar una entrada en items con id, provider (uno de anthropic | google | openai | deepseek), label, category, tier (high | mid | low) y next (otro id conocido o null).
2. Agregar el id al array correspondiente del bloque tiers. El orden dentro del tier importa: define el orden por defecto cuando alguien usa tier:high.
3. Si el proveedor todavía no tiene clase implementada (ej. OpenAI hoy), saltar al paso 5 — el catálogo lo aceptará pero las llamadas fallarán con ProviderNotConfiguredError hasta que se conecte el SDK.
4. Reiniciar la app: docker compose build app && docker compose up -d app. Redesplegar: ./deploy.sh deploy. El manifest viaja dentro de la imagen Docker, así que cambios en YAML requieren rebuild.
5. Validar con el script de auditoría: PYTHONPATH=. python scripts/audit-permission-catalog.py --check-chains. Imprime CHAIN AUDIT — OK si todo está consistente.

Tiers (alta / media / baja)

Los tiers son grupos por capacidad. Existen tres: high (modelos premium con razonamiento profundo), mid (modelos estándar con buen balance) y low (modelos económicos y rápidos para tareas simples). Una cadena puede referenciar un tier completo con la sintaxis tier:<nombre>:

model_chain:
  - tier:high     # se expande a [claude-opus-4-7, gemini-2.5-pro, gpt-5, deepseek-v4-pro]
  - tier:mid      # se expande a [claude-sonnet-4-6, gemini-2.5-flash, gpt-5-mini]

El orden dentro del tier es el orden literal del array en el manifiesto. Para reordenar dentro de un tier, edita el array tiers.<nombre>. Para reordenar solo en un caso de uso particular, lista los modelos explícitamente en lugar de usar tier: (ver Reordenar modelos).

Cadena global de fallback

global_fallback_chain en el manifiesto. Esta lista siempre se concatena al final de la cadena resuelta de cada caso de uso. Asegura que si la cadena del caso de uso solo referencia modelos no configurados, el sistema cae a una opción que sí está disponible.

global_fallback_chain:
  - gemini-2.5-flash-lite
  - gemini-2.5-flash
  - deepseek-v4-flash

Decisión (2026-05-11): cascada Google barata-a-cara con DeepSeek-flash como red de seguridad cross-vendor. gemini-2.5-flash-lite validado en pruebas reales para chat conversacional, consultas cortas y análisis estándar. gemini-2.5-pro no está en el fallback ni es preferido en ningún caso de uso — queda como override-only desde el picker del chat para tareas que ameriten razonamiento más profundo.

Ejemplo de resolución concreta: caso de uso pide [claude-opus-4-7, gpt-5], solo está configurada Gemini. El resolver descarta los dos por env-filter, concatena global_fallback_chain, queda [gemini-2.5-flash-lite, gemini-2.5-flash, deepseek-v4-flash] (más cualquier hop adicional del grafo).

Grafo de sustitución (next:)

Cada modelo tiene un next: opcional que apunta a un sucesor "inmediato" para casos donde la cadena explícita se agota. Después de aplicar la cadena del caso de uso + el fallback global, el resolver hace una caminata del grafo desde el último modelo de la cadena resuelta y agrega los sucesores no vistos (filtrados por permisos y entorno).

En la práctica, la cadena de fallback global ya cubre la mayoría de los casos. El grafo agrega redundancia adicional. Si un modelo está aislado y nunca debe sustituirse, ponle next: null.

Cadenas por caso de uso código

Cada caso de uso (src/casos_de_uso/id.md) declara su cadena en el frontmatter YAML. Tres campos opcionales:

# Cadena base (la usual):
model_chain:
  - gemini-2.5-flash
  - gemini-2.5-flash-lite

# Override por herramienta (reservado, no activado en runtime):
model_chain_by_tool:
  search_laws: [tier:low]
  risk_matrix_compute: [tier:high]

# Override por fase (reservado, no activado en runtime):
model_chain_by_phase:
  drafting: [claude-opus-4-7]
  extraction: [tier:low]

Los tres aceptan tanto IDs literales (claude-opus-4-7) como referencias de tier (tier:high). El validador rechaza cualquier referencia desconocida al cargar el caso de uso (warning en logs, caso queda fuera del catálogo hasta corregir).

Reordenar modelos dentro de un caso de uso

Tres patrones según qué tan flexible necesitas ser:

Patrón A — referencia al tier (orden del manifiesto)

model_chain:
  - tier:low   # → [claude-haiku-4-5, gemini-2.5-flash, gpt-5-nano, deepseek-v4-flash]

El orden lo decide el manifest. No tienes control fino dentro del tier.

Patrón B — lista explícita (tu orden)

model_chain:
  - deepseek-v4-flash
  - gemini-2.5-flash
  - gpt-5-nano
  - claude-haiku-4-5

El resolver respeta el orden tal cual lo escribes.

Patrón C — mezcla (cabeza explícita + cola por tier)

model_chain:
  - deepseek-v4-flash    # primero, prioridad propia de este caso
  - tier:low             # resto del tier; deepseek-v4-flash deduplicado

El resolver dedupe preservando el primero encontrado, así que la cabeza explícita gana ante empates.

Override por herramienta — reservado

El campo model_chain_by_tool existe en el schema y se valida, pero las herramientas actuales no invocan al LLM por su cuenta — todas las llamadas pasan por el provider único del agente. Cuando alguna herramienta gane su propio call site al LLM (ejemplo futuro: un extractor que llama a Haiku para procesar un anexo grande), este override empezará a tener efecto.

Override por fase — reservado

Mismo estado: el campo model_chain_by_phase existe pero el bucle del agente hoy no marca fronteras de fase. La infra (resolve_chain(phase=...)) está lista; falta declarar dónde se activa cada fase. TODOs en el código (src/agent/agent.py, src/extraction/amount_extractor.py, src/extraction/outcome_classifier.py) marcan los puntos de futura conexión.

Verificar qué modelo respondió

Tres ventanas de observabilidad disponibles hoy:

1 — Auditoría declarativa (cadenas configuradas)

PYTHONPATH=. python scripts/audit-permission-catalog.py --check-chains

Imprime, por cada caso de uso, su cadena cruda (antes de aplicar permisos y filtros de entorno). Útil para confirmar que un cambio en YAML llegó al sistema.

2 — Logs estructurados del runtime

Cada llamada a resolve_chain emite un log INFO con campos raw_chain, fallback_env, chosen. Cada salto de fallback emite un WARN con from_model, to_model, error_kind. Tail típico:

docker compose logs -f app | grep -E "resolve_chain|llm_chain_hop|llm_chain_exhausted"

# Cloud Run streaming logs (project default = activo; agrega --project=<id> si difiere)
./deploy.sh logs | grep -E "resolve_chain|llm_chain_hop|llm_chain_exhausted"
# o directo:
gcloud run services logs tail altlegal-ai --region=europe-southwest1 \
  | grep -E "resolve_chain|llm_chain_hop|llm_chain_exhausted"

# o desde Logs Explorer en la consola GCP con filtro:
#   resource.type="cloud_run_revision"
#   resource.labels.service_name="altlegal-ai"
#   textPayload =~ "resolve_chain|llm_chain_hop|llm_chain_exhausted"

3 — Eventos en el stream del chat

El stream SSE del chat ahora emite dos eventos relevantes:

• {"type": "model_preferred", "model_id": "..."} — al inicio de cada turno, con el primer modelo de la cadena.
• {"type": "done", "model_used": "...", ...} — al final del turno, con el modelo que efectivamente respondió (post-fallback). Si el primero falló y el segundo respondió, model_used ≠ model_preferred y se debe inspeccionar llm_chain_hop en los logs para ver el motivo.

4 — Pill de modelo en el header del chat UI

La cabecera del chat muestra un pill con el nombre corto del modelo activo (lee los eventos del punto 3). Tres estados visuales:

• Neutro (gris) — preferido del caso corriendo normal.
• Accent (rojo) — el usuario eligió un override desde el picker. Se aplica solo a esa sesión.
• Warning (amarillo) — la cadena cayó al siguiente modelo porque el preferido falló. El tooltip explica cuál falló.

Click en el pill abre un dropdown con la chain resuelta para el caso de uso (consume GET /api/chat/sessions/{id}/available-models). Cada opción muestra el label del manifest + tier hint (profundo / balanceado / rápido). Al elegir un modelo, SendMessageRequest.model_override viaja en el siguiente turno y LegalAgent._init_chain lo prepende a la chain. El override se limpia al cambiar de sesión o al re-elegir el preferido.

Lo que aún no hace esta app

Decisiones de scope tomadas en la v1 del sistema de cadenas. Cada uno tiene un plan de evolución registrado en el spec (docs/superpowers/specs/2026-05-01-llm-model-priority-fallback-design.md):

Casos de uso — qué son y dónde viven

Un caso de uso es una receta pre-configurada para una tarea recurrente: un prompt master, una cadena de modelos preferidos, una whitelist de herramientas, restricciones de temperatura y tokens, y metadatos para mostrarlo en el catálogo (icono, chips, sugerencias iniciales). Al activarlo en una sesión, el agente queda restringido a operar dentro de ese marco.

Los archivos viven en src/casos_de_uso/id.md. Cada archivo tiene dos secciones:

1. Frontmatter YAML entre --- al inicio: metadatos, configuración del modelo, whitelist de herramientas, datos para el catálogo.
2. Cuerpo Markdown: el prompt completo del agente (rol, misión, instrucciones, formato de respuesta esperado).

Frontmatter — campos

Cuerpo del prompt

Después del frontmatter, todo el resto del archivo es el prompt master del agente. Convención del repo: secciones numeradas en español (Rol, Misión, Corpus, Reglas, Formato de respuesta, etc.). Ejemplos en cualquier pdp-*.md. El cuerpo se inyecta literal como system_prompt en cada turno de la sesión asociada.

---
id: pdp-eipd
nombre: PDP — Evaluación de Impacto
# ... resto del frontmatter ...
---

## 1. Rol
Eres un consultor especializado en protección de datos personales bajo la
Ley N° 21.719. Operas como evaluador metódico que produce informes EIPD
estructurados...

## 2. Misión
- Identificar los tratamientos de datos personales que justifican una EIPD.
- Cuantificar riesgos por tipo de titular y categoría de dato.
...

Crear / editar un caso de uso en código código

1. Copiar src/casos_de_uso/TEMPLATE.md a src/casos_de_uso/<id>.md. El nombre del archivo no necesita coincidir con el id, pero por convención sí.
2. Editar el frontmatter respetando los tipos. id debe ser único entre todos los archivos del directorio.
3. Escribir el cuerpo del prompt.
4. Validar la sintaxis del frontmatter:

   PYTHONPATH=. python -c "from src.casos_de_uso.loader import load_all, list_enabled_use_cases; load_all(); print(len(list_enabled_use_cases()), 'casos cargados')"

   Si hay errores de validación se imprimen en stderr y el caso queda fuera del catálogo.
5. Reiniciar la app o usar el endpoint POST /api/casos-de-uso/reload (admin only) para recargar sin redeploy.

Editar desde la UI UI

La app expone editor admin para casos de uso vía la API /api/admin/casos-de-uso/<id>. Permite:

• GET — recuperar frontmatter + cuerpo en JSON.
• PUT — sobrescribir el archivo. Versionado automático: cada PUT crea una entrada en el historial; POST /api/admin/casos-de-uso/<id>/rollback/<version> revierte.
• GET /api/admin/casos-de-uso/vocab — devuelve listas válidas (icons, herramientas, artifact types) para poblar selectores del editor.

El editor en la UI vive en el panel de configuración → pestaña "Casos de uso" (cuando está habilitado por permisos). Los cambios se persisten directamente al archivo .md. Nota: editar archivos en disco desde la UI implica que para preservar los cambios entre rebuilds, hay que commitear el archivo modificado al repositorio.

Pills informativas en el listado

El listado tabular de casos de uso muestra pills al lado del nombre cuando aplican:

• tier · high — el caso configura un modelo high-tier (claude-opus-4-7, gemini-2.5-pro, gpt-5, deepseek-v4-pro) como primary del model_chain. Útil para identificar de un vistazo cuáles pasos usan un modelo más caro/potente que el default global. Útil también para auditar costos: si un caso simple aparece con la pill, probablemente sobreconfiguraste y conviene bajarlo a tier mid o low.
• multi-turno · N — el caso declara subprompts (multi-turno por chunk). N indica cuántos sub-turnos. Ver sección "Multi-turno" más abajo.

Los criterios para mostrar las pills se resuelven en cliente (web/app.js función _renderList dentro del módulo de casos de uso) leyendo el frontmatter ya cargado del backend; no requieren llamada extra.

Herramientas permitidas

El campo herramientas_permitidas es una whitelist contra el set KNOWN_TOOL_NAMES definido en src/casos_de_uso/schema.py. Si se declara, el agente solo puede invocar esas herramientas durante la sesión. Si se omite (null), todas están disponibles.

Herramientas disponibles hoy:

• Causas judiciales: query_cases, get_case_detail, get_case_timeline, get_document_text, court_statistics, get_case_amounts.
• Investigación: search_laws, acquire_norma, fetch_url, discover_sectoral_norms.
• Documentos: search_documents.
• PDP: anonymize_with_dlp, extract_structured_form, build_data_map_table, build_rat_table, risk_matrix_compute.
• Entregables: generate_google_doc, assemble_chapter_document, submit_artifact.
• Gestión: list_clients, list_client_matters, get_matter_status.

Trayectorias y pasos

Una trayectoria agrupa casos de uso ordenados que avanzan un proyecto del cliente (ej. la trayectoria consultoria-pdp-21719 tiene 19 pasos). Para hacer que un caso de uso sea un paso de trayectoria:

trayectoria: consultoria-pdp-21719
paso: 50
inputs_requeridos:
- ficha-proyecto
outputs_producidos:
- mapa-de-datos

inputs_requeridos determina qué artefactos previos deben existir aprobados para que el paso esté "desbloqueado" en la UI del proyecto. outputs_producidos determina qué artefactos pasan a estar disponibles para pasos posteriores. Tipos válidos en KNOWN_ARTIFACT_TYPES (src/proyecto_artifacts/schema.py).

Multi-turno con subprompts

Algunos pasos producen entregables tan extensos que un solo turno LLM no alcanza — el modelo trunca por el cap de max_output_tokens, o pierde calidad cuando el output supera ~4 mil tokens. Para esos casos, declarás una lista de subprompts en el frontmatter: el chat ejecuta cada entrada como un sub-turno LLM separado, acumula los outputs y al final emite UN solo entregable consolidado del tipo declarado en outputs_producidos.

Cuándo usarlo

• Entregables con secciones canónicas independientes — ej. la Sección III del Informe PDP tiene 9 ejes (3.1 a 3.9), cada uno requiere razonamiento profundo. Cada eje queda como sub-turno.
• Outputs sobre ~6 mil palabras donde la coherencia inter-sección es razonable pero no esencial.
• NO usar para entregables cortos (one-shot está bien), ni para tareas conversacionales (el formato multi-turno asume entregable estructurado).

Schema

subprompts:
- "Redacta el eje 3.1 — Políticas generales y específicas. Estructura: Diagnóstico → Recomendaciones → Tabla de prioridad/complejidad/medios."
- "Redacta el eje 3.2 — Procedimientos y manuales operativos. Mismo formato."
- "Redacta el eje 3.3 — Reglamento Interno (RIOHS). Mismo formato."
# … hasta 20 entradas
outputs_producidos:
- seccion-iii-brechas       # exactamente UN tipo (validado por el schema)

Reglas y validaciones

• 2 a 20 entradas. Menos de 2 no tiene sentido (es un single-turn) y más de 20 indica que el caso debería partirse en pasos separados.
• Cada entrada ≤ 4096 caracteres. Si necesitas más, factoriza al cuerpo del prompt master que reciben todos los sub-turnos.
• outputs_producidos debe declarar exactamente 1 tipo — el handler emite UN artefacto consolidado, no varios. Validado en schema.py:_subprompts_requires_one_output.
• Cada sub-turno hereda el mismo system prompt (cuerpo del .md), las mismas herramientas_permitidas, la misma model_chain y los mismos artefactos previos del proyecto. Solo cambia el "user message" de cada sub-turno (la entrada de subprompts).

Comportamiento en runtime

• El handler de chat detecta el campo y bifurca a _multi_turn_stream en src/chat/routes.py.
• Cada sub-turno crea un LegalAgent nuevo (mismo DB session) — esto previene acumulación de estado entre sub-turnos del provider.
• Antes de acumular el output de un sub-turno se aplica _strip_postproc_warning para remover el banner "⚠️ Entregable no registrado" que el postprocesador agrega cuando el sub-turno no llama submit_artifact (lo cual es lo esperado: solo el último sub-turno o un follow-up del usuario invoca submit).
• El stream emite eventos subturn_start con {n, total} antes de cada sub-turno y subturn_end al cerrar — el frontend usa esto para pintar el separador ▍ Turno N/total.
• El historial inter-sub-turno se truncan a los últimos 2000 caracteres del output anterior (suficiente para mantener coherencia sin saturar el contexto).
• Citas de cada sub-turno se acumulan en una lista única emitida en el done consolidado.

Ejemplos en el repo

• pdp-informe-seccion-iii.md — 12 sub-prompts (9 ejes + 3 sub-brechas del eje 3.9). Tiempo típico: 7–11 minutos.
• pdp-informe-seccion-iv.md — 5 sub-prompts (3 tablas + Conclusión + Anexo). Tiempo típico: 4–6 minutos.

UI esperada

Para que el abogado entienda por qué la respuesta llega en bloques, documenta el caso en web/ayuda-consultoria-pdp.html con la pill multi-turn — N sub-prompts y describe los ejes. Ver paso 130 / 140 como referencia.

Validación y reload

• Boot: el loader registra cada archivo válido en el catálogo. Errores de schema se imprimen como WARN en logs y el caso queda fuera.
• Reload sin redeploy: POST /api/casos-de-uso/reload (requiere admin). Re-lee todo el directorio y reemplaza el catálogo en memoria. Sesiones existentes mantienen su prompt original (cargado al crear).
• Auditoría de chains: scripts/audit-permission-catalog.py --check-chains detecta referencias a modelos / tiers desconocidos en cualquier model_chain*.

Equipos y permisos — modelo conceptual

El sistema combina cuatro entidades:

• Usuario (users) — identidad federada vía Google OAuth. Atributos clave: email, role (admin | user), profile (abogado | paralegal | null).
• Equipo (teams) — unidad funcional del estudio. Ejemplos: Gerencia, Administración, Corporativo, Litigios. Un usuario puede pertenecer a varios.
• Perfil — rol jurídico transversal (abogado, paralegal). Cada usuario tiene a lo sumo uno.
• Política (permission_policies) — regla de allow/deny sobre un tipo de recurso, con un alcance (team / profile / user_override).

Tipos de recurso permisionables

Políticas y precedencia

Una política tiene cuatro campos clave:

• scope_type: team | profile | user_override
• scope_ref: el id del team / profile / user al que aplica
• resource_type: tipo de recurso (tabla arriba)
• mode: allow | deny
• resource_ids: array de ids o globs (ej. ["claude-opus-*"])

Resolución para un usuario en runtime:

1. user_override gana siempre. Una política con scope_type='user_override', scope_ref=<email> tiene precedencia absoluta. Si dice allow [X], X queda permitido aunque su team lo deny.
2. profile luego. Aplica si el usuario tiene ese profile.
3. team al final. Si el usuario pertenece a varios teams, sus políticas se combinan: cualquier deny gana entre teams (la unión de denies).
4. Default cerrado: si no hay ninguna política allow que cubra el recurso, queda denegado. La excepción es admin.

Glob expansion: las policies pueden contener wildcards (*, ?, [...]) que se expanden contra el catálogo del resource_type al resolver. Ejemplo: "claude-opus-*" matchea cualquier id que empiece con claude-opus- en el manifest de modelos.

CRUD desde la UI UI

Configuración → pestaña "Equipos y permisos". Solo visible para usuarios con role=admin.

Gestión de equipos

• Crear equipo: botón "Nuevo equipo" → nombre + descripción.
• Agregar miembros: dentro de un equipo, "Agregar miembro" → buscar usuario por email. Solo usuarios con sesión previa aparecen.
• Eliminar miembro: ícono X junto al usuario.
• Soft-delete del equipo: botón "Eliminar". Conserva auditoría; las políticas del equipo dejan de aplicar.

Asignación de perfil

Dentro de un equipo, para cada miembro se puede setear el profile (abogado | paralegal | sin perfil) directamente con un selector inline.

Editor de políticas

Para cada equipo (o profile, o user_override), aparece un editor con un selector de tipo de recurso → checkboxes con los items del catálogo + campo de "globs adicionales". Al guardar, se hace upsert: si ya existía una policy con ese (scope, resource_type), se reemplaza. Borrar todos los checkboxes y los globs equivale a "todo denegado por default" para ese recurso/scope.

Patrones glob

Útil para reglas amplias sin enumerar cada id. Ejemplos prácticos:

# Negar a paralegales el acceso a cualquier modelo Opus (futuro o presente):
scope: profile=paralegal
resource_type: llm_model
mode: deny
resource_ids: ["claude-opus-*"]

# Permitir a un equipo solo herramientas de causas judiciales:
scope: team=Litigios
resource_type: tool
mode: allow
resource_ids: ["query_cases", "get_case_*", "court_statistics", "search_documents"]

# Permitir a un usuario específico todos los pasos de PDP:
scope: user_override=ana@altlegal.cl
resource_type: paso_caso_uso
mode: allow
resource_ids: ["pdp-*"]

Auditoría

Hay dos capas de auditoría complementarias:

1. Catálogo de permisos vs políticas existentes — el script scripts/audit-permission-catalog.py detecta inconsistencias estáticas (orphans + cadenas LLM rotas).
2. Histórico de mutaciones — toda creación / edición / borrado de team, miembro, perfil o política queda registrada en tenant_altlegal.audit_events (eventos policy_upserted, policy_deleted, team_*, profile_updated, user_role_changed). Visible en Configuración → Actividad → Eventos. Detalle en Actividad — telemetría.

Modos del script:

• Default (--check-orphans): lista resource_ids en políticas que no existen en el catálogo. Detecta typos y referencias a items removidos.

  PYTHONPATH=. python scripts/audit-permission-catalog.py

• --check-chains: valida cadenas model_chain* en YAMLs de casos de uso contra el manifest. Imprime cadenas efectivas por caso.

  PYTHONPATH=. python scripts/audit-permission-catalog.py --check-chains

Ambos retornan exit code 1 si encuentran inconsistencias — útiles para CI o git hooks.

Bypass de admin

Usuarios con role='admin' bypasean toda la lógica de permisos: ven todos los menús, todas las herramientas, todos los modelos, todos los pasos. La cadena LLM resuelta para un admin no aplica filtros de permisos (sí aplica el filtro de claves API configuradas — un admin sin claves de Anthropic igual no puede llamar a Claude).

Cambiar el rol de un usuario hoy es operación de DB:

docker compose exec db psql -U postgres -d legal_ai -c \
  "UPDATE tenant_altlegal.users SET role='admin' WHERE email='dtorres@altlegal.cl';"

# Conectar via Cloud SQL Auth Proxy (corre detrás de IAM, no expone la DB pública):
gcloud sql connect altlegal-ai-pg --user=postgres --database=legal_ai \
  --quiet << 'EOF'
UPDATE tenant_altlegal.users SET role='admin' WHERE email='dtorres@altlegal.cl';
EOF

El usuario debe cerrar sesión y volver a entrar para que el cambio surta efecto.

Impersonación — "Ver como otro usuario" UI

Para debuggear permisos sin loguearse como otro usuario, un admin puede iniciar una sesión de solo lectura que se comporta como si fuera otro user. Útil para validar "¿el paralegal Y realmente no puede aprobar artefactos? ¿el team Z ve el menú Configuración?" sin interrumpir al usuario afectado.

Cómo se inicia

1. Configuración → Usuarios.
2. Junto a cada user (excepto tú mismo) aparece el botón "Ver como".
3. Click → confirm modal. Acepta para iniciar.
4. La página recarga. Aparece un banner amarillo arriba: "Estás viendo como X (sesión real: Y). Modo lectura.".
5. Mientras dure la impersonación, todos los menús, casos de uso, modelos LLM, sesiones, etc. se filtran como los vería el target.
6. Para terminar: click en Salir en el banner.

Modo lectura forzado

Mientras hay una sesión de impersonación activa, un middleware del backend bloquea cualquier request HTTP que no sea GET / HEAD / OPTIONS con respuesta 423 Locked. Excepción: los endpoints del propio sistema de impersonación (POST /api/admin/impersonate/{id} y DELETE /api/admin/impersonate) siempre pasan.

Esto previene que un admin haga mutaciones (crear sesiones, aprobar artefactos, subir documentos, cambiar permisos) bajo la identidad de otro user — escenario que ensuciaría el audit log y abriría una puerta a auditorías ambiguas.

Mecánica interna

• Cookie separada altlegal_impersonate, firmada con el mismo secret que la sesión normal pero con salt distinto. Payload: {user_id: int}. TTL: 1 h (más corto que la sesión, porque es para una tarea puntual).
• get_current_user en src/auth/dependencies.py hace el swap: si el caller real es admin Y la cookie de impersonación apunta a un user válido, devuelve el target con atributos dinámicos _impersonated_by_email / _impersonated_by_id. Si el caller real NO es admin, la cookie se ignora (defensa en profundidad ante tampering).
• get_real_admin_user dependency separada que bypassa el swap — usada por los endpoints de impersonación para que un admin impersonando pueda llamar a DELETE /admin/impersonate.
• Audit log: dos eventos nuevos en AuditEventType — impersonation_started y impersonation_ended. El actor es siempre el admin real; target_id es el user impersonado.

Limitaciones conocidas

• Si quieres cambiar de target durante una sesión de impersonación, primero debes salir — el modo lectura oculta el menú Usuarios para targets non-admin.
• Las cachés in-process (permisos, bundle de chat) se rehidratan al hacer reload completo después de iniciar la impersonación. No hay invalidación más fina.
• WebSockets / SSE iniciados antes de la impersonación siguen corriendo bajo la identidad original hasta cerrarse — pero el middleware bloquea el siguiente POST /api/chat/sessions/{id}/message, así que en práctica cualquier acción de chat queda capturada.

ACL por documento — cómo funciona

Sistema de acceso granular a documentos individuales (Phase 4 — 2026-05-02; profile-scope agregado 2026-05-10). Ortogonal al sistema de permisos por tipo de recurso: aquí cada documento tiene su propia lista de equipos, perfiles o personas que pueden verlo y usarlo.

Default opt-in restrictivo: al crearse, un documento es visible para cualquier usuario autenticado del estudio (preserva el comportamiento histórico). Para volverlo confidencial, el propietario activa Restringir acceso y elige quién puede acceder. Spec: docs/superpowers/specs/2026-05-02-document-acl-design.md.

Schema (tenant_altlegal):

• user_documents.is_restricted — booleano (default false).
• document_acl(document_id, scope_type ∈ {team, user, profile}, scope_ref, created_by_user_id) — una fila por equipo, perfil o persona compartida. scope_ref contiene: UUID del team, user.id como string, o el string del perfil ('abogado' / 'paralegal'). Cascade delete desde user_documents. Unique en (document_id, scope_type, scope_ref). CHECK constraint enforced (migration 032_document_acl_profile_scope).

OR de scopes: cualquier match grants. Un doc con ACL [team X, profile Abogado] es accesible a un paralegal en team X (match team) Y a un abogado fuera de X (match profile). El usuario que pierde membresía de team X y no tiene perfil Abogado pierde acceso inmediatamente (no se cachea grant cross-session).

Orden de resolución

El resolver src/documents/acl.py::user_can_access_document evalúa así, short-circuit en el primer True:

1. Documento no existe o soft-deleted → False.
2. Documento no restringido (is_restricted = false) → True. Salta todo el resto. Es el caso común; cuesta una sola query.
3. Owner — document.uploader_email == user.email → True. El propietario siempre ve su documento; no se puede revocar desde la UI.
4. Admin bypass — user.role == 'admin' → True.
5. User-scope ACL match — existe una fila con scope_type='user' y scope_ref=str(user.id) → True.
6. Profile-scope ACL match — el usuario tiene user.profile definido (abogado / paralegal) y existe una fila con scope_type='profile' y scope_ref=user.profile → True. Usuarios sin perfil (NULL) no matchean esta rama; deben recibir acceso por team o user individual.
7. Team-scope ACL match — el usuario es miembro de algún equipo en la lista de ACL (filtrando equipos soft-deleted) → True.
8. Caso contrario → False, registra WARN document_access_denied en logs.

Hay un helper bulk paralelo, filter_accessible_document_ids(user_id, document_ids) -> set[int], optimizado para listados (una query por capa, no N por documento).

Caché 60s TTL keyed por (user_id, document_id). Invalidación al cambiar is_restricted, al modificar ACL, o al cambiar membership de team.

Dónde se aplica el ACL

Cuatro sitios consultan el resolver:

Compartir desde la UI UI

Dos puntos de configuración de ACL:

• Al subir — el modal de upload pregunta "¿Restringir acceso?" antes de mandar el archivo. Si el toggle se marca, el doc se sube y queda is_restricted=true con ACL vacío (solo owner + admins lo ven). El owner completa equipos/perfiles/personas después desde el menú ⋯.
• Post-upload — En la tabla de Documentos, el menú ⋯ de cada fila tiene la entrada Compartir…. Abre un modal completo con todos los pickers.

El modal de Compartir muestra:

• Propietario — fila no editable, indicando el email de quien subió el documento.
• Toggle Restringir acceso — apagado = documento visible globalmente; encendido = solo los listados abajo más el owner y admins lo ven.
• Equipos con acceso — multi-select con autocomplete sobre el listado de teams. Cada selección aparece como chip con × para quitar.
• Perfiles con acceso — multi-select con Abogado / Paralegal. Útil para "que todos los abogados vean este doc, sin tener que listar a cada uno". Usuarios sin perfil (NULL) no entran por esta vía.
• Personas con acceso — multi-select con autocomplete sobre el listado de usuarios (excluyendo al propietario, que ya tiene acceso implícito).
• Warning automático — si el toggle está encendido pero ningún equipo / perfil / persona seleccionado, aparece "Solo tú y los admins podrán acceder".

Al guardar, el badge 🔒 Restringido aparece junto al nombre del documento en la tabla. La caché del resolver se invalida automáticamente para ese document_id.

Permission gate: solo el propietario del documento o un admin puede abrir el modal y guardar cambios. Otros usuarios reciben HTTP 403.

API endpoints código

GET    /api/documents/{id}/acl     # estado actual + labels (team name, user email)
POST   /api/documents/{id}/acl     # idempotente; wipe + reinsert
DELETE /api/documents/{id}/acl     # equivalente a POST {is_restricted: false, teams:[], users:[]}

GET    /api/share-targets          # lista teams + users para los pickers (cualquier autenticado)

POST body:

{
  "is_restricted": true,
  "teams": ["<team_uuid>", "<team_uuid>"],
  "users": [17, 42],
  "profiles": ["abogado"]
}

Errores: 400 ante UUID de team, user_id, o perfil desconocido (válidos: abogado, paralegal); 403 para non-owner non-admin; 404 doc no encontrado o soft-deleted.

Auditoría: cada mutación emite un INFO log estructurado document_acl_changed con actor_user_id, document_id, before, after. Cada denial (resolver) emite WARN document_access_denied.

Quién puede subir documentos Política

Reglas hardcoded en los endpoints POST /documents/upload y POST /documents/drive-pick (Fase B ACL, 2026-05-10):

Frontend: los botones Subir documento e Importar desde Drive en la biblioteca tienen data-admin-only y se ocultan via applyAdminOnlyGates() a usuarios no-admin. Si admin entra a "Ver como" un viewer, los botones se ocultan también. El backend igual rechaza con 403 — la UI es solo para no mostrar botones inútiles.

Promoción futura a policy-driven: hoy la regla está hardcoded. Cuando llegue el caso real de "el team X puede subir a biblioteca pero el Y no", se eleva a resource_type='feature' con manifest yaml y items upload_library, upload_chat, ambos editables desde el policy editor. Ver entry en docs/next-phases.md § "Acceso granular a documentos".

Lo que aún no hace esta app

Tracking en docs/next-phases.md § "Phase 4 follow-ups → Acceso granular a documentos":

Accesos a Drive — Modelo C

La app gestiona accesos a las carpetas de Drive de cada matter (proyecto) sincronizándolos con el ACL de la app. La cuenta de servicio app-sa@altlegal-ai.iam.gserviceaccount.com mantiene los permisos del folder del matter alineados con las políticas de tipo resource_type='matter'.

Modelo de seguridad:

Regla central: si un usuario non-admin no tiene ACL en un matter, no puede acceder al folder del matter ni vía la app ni vía Drive UI directo. El ACL de la app es la fuente de verdad.

Layout del Shared Drive

Convención operativa (la app no impone la ruta — sólo gestiona permisos al folder id linkeado):

Shared Drive root
├── Documentos/                       ← reservado para chat + Compartidos
│   ├── PROD/
│   │   ├── Compartidos/              ← shared con team General (todos)
│   │   └── <user-email>/             ← per-user session uploads
│   └── LOCAL/                        ← idem para env local
└── Clientes/
    └── <Cliente>/                    ← folder padre del cliente (opcional)
        └── <Proyecto>/               ← matter folder (linkeado a matter.drive_folder_id)
            └── ...                   ← contenido del proyecto

Vincular un folder a un matter UI

Antes de vincular: la cuenta de servicio app-sa@altlegal-ai.iam.gserviceaccount.com debe tener acceso al folder. Si no lo tiene, el endpoint responde HTTP 400 con instrucción explícita.

1. Crea (o ubica) el folder en Clientes/<Cliente>/<Proyecto>/ del Shared Drive.
2. En Drive UI → Compartir → pega app-sa@altlegal-ai.iam.gserviceaccount.com como Editor o Content manager. Sin notificación.
3. En la app → vista del matter → "Vincular carpeta de Drive" → pega el ID o la URL. El validador acepta ambos formatos (URL → ID se normaliza automáticamente).
4. Al guardar, el link valida acceso de la SA (preflight) y dispara reconcile inmediato. Si ya existían policies sobre ese matter, los grants se aplican al instante.

Conceder accesos por policy

El mecanismo de granularidad vive en Configuración → Equipos → Políticas, sección Proyectos (Matters). Cada matter es un recurso independiente: una policy lista UUIDs específicos de matters, no clientes ni patrones.

Acceso por team

Ejemplo: Cliente X con 4 proyectos. Team Judicial debe ver los 2 laborales; team Corporativo los 2 de M&A.

team='Judicial'    → resource_type='matter' mode='allow' resource_ids=[uuid_laboral_1, uuid_laboral_2]
team='Corporativo' → resource_type='matter' mode='allow' resource_ids=[uuid_mya_1, uuid_mya_2]

Resultado en Drive:

• Miembros de Judicial ven los 2 folders laborales en "Compartido conmigo". No ven los corporativos.
• Miembros de Corporativo ven sólo los corporativos.
• Si un usuario está en ambos teams: union de allows (ve los 4).
• Si alguien sale del team Judicial: el siguiente reconcile (al editar la policy) le revoca acceso a los 2 folders laborales.

Acceso por user_override

Para accesos individuales sin meter al usuario en un team:

• scope_type='user_override' con mode='allow' + resource_ids=[<uuid>] → grant puntual. Caso típico: paralegal externa que entra a un proyecto específico, o cliente que necesita ver entregables.
• scope_type='user_override' con mode='deny' → revoca acceso a un miembro del team para un matter sin sacarlo del equipo. Caso: conflicto de interés.

Compartir manualmente desde Drive UI

El reconcile sólo gestiona permisos directos en la carpeta raíz del matter (matter.drive_folder_id). Los grants heredados se ignoran (vía permissionDetails.inherited=true). Esto define qué shares manuales sobreviven:

Cuándo se ejecuta el reconcile

El reconcile (reconcile_matter_acl_to_drive) corre como tarea asyncio fire-and-forget cuando:

• Se hace upsert de una policy de tipo matter → reconcile sobre union(old_resource_ids, new_resource_ids).
• Se hace delete de una policy de tipo matter → reconcile sobre todos los matters afectados.
• Se vincula un folder a un matter (PUT /matters/{id}/drive-folder) → reconcile sobre ese matter.
• Manualmente via script: PYTHONPATH=. python scripts/backfill-matter-drive-permissions.py --apply [--matter-id <uuid>]

Latencia esperada: el endpoint HTTP retorna inmediato. El reconcile toma 1-5s por matter; el usuario ve el folder en su Drive ~1-5s después del cambio de policy.

Comportamiento del reconcile:

1. Carga el matter; si drive_folder_id es NULL, retorna skipped_no_folder=True y registra el audit event sin tocar Drive.
2. Resuelve los emails autorizados desde permission_policies (expande team via team_members; user_override via user id; profile-scope queda como warning + skip en v1).
3. Lista permisos directos del folder vía Drive API (filtra heredados y no-user).
4. Aplica diff: grants nuevos + revokes de los que sobran. Cada grant/revoke es independiente; un fallo no detiene los demás.
5. Emite audit event matter_drive_sync con el resumen completo.

Auditoría y verificación

Cada reconcile emite un evento matter_drive_sync en tenant_altlegal.audit_events. Payload:

{
  "folder_id": "1abc...",
  "granted": ["fsanchez@altlegal.cl"],
  "revoked": [],
  "unchanged_count": 3,
  "errors": [],
  "skipped_no_folder": false
}

Para verificar la última sync de un matter (consola psql vía Cloud SQL Proxy):

SELECT created_at, payload
FROM tenant_altlegal.audit_events
WHERE event_type = 'matter_drive_sync'
  AND target_id = '<matter_id>'
ORDER BY created_at DESC LIMIT 3;

Para ver el log en Cloud Run:

gcloud logging read 'resource.type=cloud_run_revision \
  AND resource.labels.service_name=altlegal-ai \
  AND textPayload:"matter_drive_sync"' \
  --limit=20 --freshness=1h --project=altlegal-ai

Troubleshooting

Lo que aún no hace

Actividad — telemetría y audit log

Phase 4.2 (mayo 2026) shippea persistencia de eventos críticos del sistema. Resuelve dos preguntas que antes solo respondían los logs de stdout:

• "¿Quién hizo qué y cuándo?" — mutaciones de configuración, equipos, políticas, artefactos, documentos, ACLs, sesiones de chat.
• "¿Qué modelo respondió, cuántos tokens consumió, cuánto demoró, hubo fallback?" — una fila por cada llamada al ResilientProvider.

Implementación: dos tablas narrow bajo tenant_altlegal, escritura asíncrona / fail-soft (detalle), viewer paginado en la pestaña Actividad de Configuración.

Eventos auditables

21 tipos de eventos en producción, divididos por dominio. Cada fila en audit_events persiste: event_type, actor_user_id (FK users.id con SET NULL en delete), actor_email (snapshot — sobrevive el delete del user), target_type + target_id (referencia al objeto mutado) y payload JSONB con la diff o snapshot relevante.

Lo que NO se loggea: mensajes individuales de chat (volumen alto, valor bajo — el histórico ya vive en chat_messages); lecturas de cualquier tipo (lista de docs, queries al corpus).

El catálogo de eventos es un Literal cerrado en src/audit/types.py. Agregar uno nuevo requiere code edit + spec update — no se puede inyectar tipos arbitrarios desde la UI.

Uso LLM (tokens y latencia)

Cada llamada exitosa a ResilientProvider.generate() o generate_stream() persiste una fila en tenant_altlegal.llm_call_log con:

• user_id + user_email (snapshot), session_id, caso_de_uso_id, matter_id — contexto de la llamada.
• model_id (ej. claude-sonnet-4-6) + provider (anthropic / google / deepseek / openai).
• tokens_in + tokens_out — extraídos de la respuesta del proveedor (cada provider expone _extract_usage con su mapeo específico).
• latency_ms — tiempo total desde antes del primer intento hasta éxito (incluye hops de fallback).
• hop_count — 0 si el modelo primario respondió; ≥1 si hubo fallback.
• error_kind — NULL en éxito; el kind del último error (rate_limit, timeout, auth, etc.) si la cadena se agotó completa.

Edge cases:

• Provider devuelve sin objeto usage → tokens=0 + WARN log usage_extract_failed. La fila igual se persiste.
• Streaming con fallback antes de emitir → registra el modelo que efectivamente emitió, hop_count = hops fallidos previos.
• Streaming con fallback mid-stream → no hay fallback (contrato del ResilientProvider). Loggea como exhaustion con error_kind del error que rompió el stream.
• Cadena exhausta (todos los modelos fallaron) → fila con tokens_in=0, tokens_out=0, hop_count = chain length, error_kind del último error.

Pestaña Actividad UI

Configuración → Actividad. Solo visible para admins. Dos sub-vistas:

Eventos

• Tabla paginada (20/pág) ordenada por timestamp descendente.
• Filtros: dropdown por event_type, fecha desde / hasta. Click en "Actualizar" recarga.
• Cada fila: timestamp, actor email, pill con event_type, target_type:target_id, y un <details> expandible con el payload JSONB completo.

Uso LLM

• Selector segmented por bucket de tiempo: este mes (default) / últimos 7 días / últimos 30 días.
• Group_by dropdown: por modelo / proveedor / caso de uso / usuario.
• Tabla agregada con: clave, total de calls, tokens in, tokens out, total tokens, latencia promedio (ms), % fallback (porcentaje de calls donde el primario falló).
• Footer con suma global del período.

El % fallback es la métrica más útil para detectar problemas de proveedor: si Claude Sonnet sube de 0% a 15%, probablemente Anthropic está rate-limiteando — momento de revisar la cadena fallback en el manifiesto LLM.

Calidad PDP UI

Sub-pestaña dedicada al ciclo de vida de los entregables. Cruza eventos artifact_submitted ↔ artifact_approved / artifact_rejected por target_id (id del artefacto) y agrupa por tipo. Por cada tipo de entregable muestra:

• Aprobados / Descartados / En curso — counts en el período.
• % aprobación = approved / (approved + rejected). Coloreado: ≥90 verde, ≥70 amarillo, ≥50 naranja, <50 rojo. Indicador rápido de qué tipos requieren rework frecuente.
• TTA mediana / p90 — time-to-approve, distancia entre el submit y el approve dentro del mismo target_id. Formato auto: s/min/h/d. Detecta pasos lentos (un TTA p90 de 3 días señala que el aprobador está ahogado o el draft requiere mucha edición).

Selector segmented por bucket: últimos 7 / 30 días / este mes / total. El filtro aplica al evento terminal — un draft submitido fuera de la ventana sigue contando si su aprobación cae dentro.

Flujo de uso típico: tras una semana de operación, ordenar por aprobados + descartados descendente para ver los tipos más frecuentes; revisar % aprobación bajo (<70 sugiere mejorar el prompt master del caso de uso); revisar TTA p90 alto (>1 día sugiere reasignar aprobadores).

API endpoints código

Todos admin-only (require_admin). Útiles para automatización, reporting externo o exportar a un BI.

Garantía fail-soft

Tanto log_event como log_llm_call wrap su trabajo en un try / except Exception: una falla de DB, un payload malformado o un cierre del event loop nunca rompen la acción del usuario que los disparó. En caso de error:

• Se loggea WARN a stdout (audit_write_failed o llm_log_write_failed) con event_type / model_id + repr(error).
• La función retorna None. El handler HTTP / la herramienta del agente no se entera.

Implicación: si la pestaña Actividad muestra menos eventos de los esperados, hay que revisar los logs por audit_write_failed. La ausencia de la fila NO significa que la acción no ocurrió.

El log_llm_call usa asyncio.create_task fire-and-forget, de modo que el writer abre su propia DB session — esto desacopla la escritura del request lifecycle (la respuesta del usuario sale antes de que el row se escriba).

Crecimiento y purga

Volumen esperado en uso interno:

• audit_events: 50–200 filas/día. Insignificante.
• llm_call_log: ~20–50 calls/sesión × ~10 sesiones/abogado/día × 5 abogados → ~2.500 filas/día. Postgres se ríe; en un año son ~900K, todavía cómodo.

No hay TTL automático en v1. Si en algún momento el tamaño preocupa, purga manual recomendada (siempre con backup primero):

# Snapshot antes de borrar
docker compose exec db pg_dump -U postgres -d legal_ai \
    -t tenant_altlegal.audit_events \
    -t tenant_altlegal.llm_call_log \
    > /tmp/telemetry-snapshot-$(date +%Y%m%d).sql

# Conservar últimos 12 meses de audit
docker compose exec db psql -U postgres -d legal_ai -c "
DELETE FROM tenant_altlegal.audit_events
 WHERE created_at < now() - interval '12 months';
"

# Conservar últimos 90 días de llm_call_log
docker compose exec db psql -U postgres -d legal_ai -c "
DELETE FROM tenant_altlegal.llm_call_log
 WHERE created_at < now() - interval '90 days';
"

# Snapshot a Cloud Storage antes de borrar (Cloud SQL exporta directo a GCS)
gcloud sql export sql altlegal-ai-pg \
    gs://altlegal-ai-backups/telemetry-$(date +%Y%m%d).sql \
    --database=legal_ai \
    --table=tenant_altlegal.audit_events,tenant_altlegal.llm_call_log

# Conservar últimos 12 meses de audit
gcloud sql connect altlegal-ai-pg --user=postgres --database=legal_ai \
  --quiet << 'EOF'
DELETE FROM tenant_altlegal.audit_events
 WHERE created_at < now() - interval '12 months';
EOF

# Conservar últimos 90 días de llm_call_log
gcloud sql connect altlegal-ai-pg --user=postgres --database=legal_ai \
  --quiet << 'EOF'
DELETE FROM tenant_altlegal.llm_call_log
 WHERE created_at < now() - interval '90 days';
EOF

Phase 6 va a automatizar esto con un job programado.

Lo que aún no hace esta app

Decisiones de scope al cerrar Phase 4.2. Tracking en docs/next-phases.md § "Telemetría operacional":

Despliegue — visión general

La plataforma corre en dos entornos:

El frontend (HTML + JS + CSS) detecta el host al cargar esta página y muestra los comandos del entorno apropiado. Puedes flipear manualmente con el toggle del top.

deploy.sh código

Script único e idempotente, en la raíz del repo. Reemplaza un set ad-hoc de gcloud + Makefiles que tenía que recordar cada admin. Toda operación verifica el estado actual antes de aplicar cambios — correrlo dos veces seguidas no rompe nada.

Naming canónico (per gcp-conventions skill): project altlegal-ai (acepción al patrón altlegal-app-<workload> por ser inmutable), region europe-southwest1 (co-localizada con Vertex AI), Cloud SQL altlegal-ai-pg, Cloud Run service altlegal-ai, SAs app-sa y jobs-sa, secrets en kebab-case (claude-api-key, database-url, etc.).

Subcomandos disponibles:

Bootstrap inicial de un entorno

Correr una vez al crear un proyecto GCP nuevo. Flow recomendado paso-a-paso:

# 1. Una vez por máquina
gcloud auth login
gcloud config set project altlegal-ai
gcloud auth application-default login   # ADC para Vertex desde local

# 2. Configurar .env.deploy
cp .env.deploy.example .env.deploy
# Editar: DB_PASSWORD, LEGAL_AI_SESSION_SECRET (openssl rand)
# Opcional: LEGAL_AI_CLAUDE_API_KEY, LEGAL_AI_DEEPSEEK_API_KEY, etc.

# 3. Pipeline greenfield (cada subcomando es idempotente)
./deploy.sh init                  # ~10 min (Cloud SQL es lento)
./deploy.sh deploy                # primer Cloud Run (sin secrets aún; URL listo)
./deploy.sh oauth                 # instrucciones para crear OAuth Client
                                  # — paso manual en Google Console
# editar .env.deploy con OAuth client_id + client_secret
./deploy.sh secrets sync          # sube secrets a Secret Manager
./deploy.sh deploy                # re-deploy: Cloud Run picks up secrets
./deploy.sh migrate               # alembic via Cloud Run Job (idempotente)
./deploy.sh seed-corpus           # dump local + import a Cloud SQL
./deploy.sh seed-admin            # opcional: user admin + team General

# 4. Verificar
./deploy.sh status                # todo ✓
./deploy.sh url                   # URL pública del Cloud Run service

# 5. Dominio custom (opcional, una vez)
gcloud beta run domain-mappings create \
    --service altlegal-ai \
    --domain app.altlegal.cl \
    --region europe-southwest1

Cambios iterativos

Workflows típicos por tipo de cambio:

Dominio personalizado — visión general

La app es accesible vía https://altlegal.paralegal.technology (dominio gestionado en GoDaddy, mapeado a Cloud Run mediante domain mapping nativo). Certificado SSL provisto por Google Cloud (managed) — auto-renueva sin intervención.

Por qué Bélgica para Cloud Run

El gcloud beta run domain-mappings create NO está disponible en Madrid (europe-southwest1). Google sólo soporta domain mappings nativos en un subconjunto de regiones (entre ellas europe-west1, europe-west4, us-central1). Las alternativas eran:

• Global External Load Balancer sobre Cloud Run Madrid — funciona pero cuesta ~$18 USD/mes extra (forwarding rule + LB).
• Mover Cloud Run a Bélgica — gratis, latencia 5ms Bélgica↔Madrid sobre la DB.

Se eligió la segunda. Cloud SQL queda en Madrid (no se movió para evitar migración de datos). Cloud Run conecta vía Cloud SQL Auth Proxy cross-region, latencia despreciable.

Crear / modificar domain mapping código

gcloud beta run domain-mappings create \
    --service=altlegal-ai \
    --domain=altlegal.paralegal.technology \
    --region=europe-west1 \
    --project=altlegal-ai

El comando devuelve los records DNS requeridos. Mientras DNS no esté propagado el cert managed espera en estado CertificateProvisioning.

Verificar estado del mapping:

gcloud beta run domain-mappings describe \
    --domain=altlegal.paralegal.technology \
    --region=europe-west1 --project=altlegal-ai \
    --format='value(status.conditions[].type,status.conditions[].status)'

Salida esperada en estado operativo: Ready=True · CertificateProvisioned=True · DomainRoutable=True.

Records DNS en GoDaddy

Una vez creado el mapping, agregar el CNAME al dominio en GoDaddy:

Type:  CNAME
Name:  altlegal
Value: ghs.googlehosted.com.
TTL:   600

Propagación típica: 5-30 min. Verificar con:

dig altlegal.paralegal.technology +short
# Debe devolver: ghs.googlehosted.com. seguido de una IP de Google

OAuth redirect URIs código

Tras activar el dominio, agregar a Google Cloud Console → APIs & Services → Credentials → OAuth client altlegal-ai:

• Authorized redirect URIs: https://altlegal.paralegal.technology/auth/callback
• Authorized JavaScript origins: https://altlegal.paralegal.technology

Sin esto, el login falla con redirect_uri_mismatch. Mantener los URIs anteriores (URL *.run.app) como respaldo durante el cutover.

SSL cert managed

Google provee y renueva automáticamente un certificado SSL gestionado para el dominio mapeado. Estado:

gcloud beta run domain-mappings describe \
    --domain=altlegal.paralegal.technology \
    --region=europe-west1 --project=altlegal-ai \
    --format='value(status.conditions[?type="CertificateProvisioned"].status)'

Si el cert queda en Unknown > 1 h tras configurar el CNAME: probable issue de DNS (no propagó al validador de Google). Revisar dig. Si FAILED_NOT_VISIBLE: el record CNAME no está visible públicamente todavía.

Rollback / re-mapping

Si el dominio nuevo falla y necesitas volver al URL *.run.app

El URL automático altlegal-ai-tpuelbed5a-ew.a.run.app sigue activo siempre, en paralelo al dominio custom. Apuntar usuarios a esa URL es rollback inmediato. Sin acciones.

Mover el dominio a otra región / service

# 1. Eliminar el mapping actual
gcloud beta run domain-mappings delete \
    --domain=altlegal.paralegal.technology \
    --region=europe-west1 --project=altlegal-ai

# 2. Crear el nuevo mapping en la región/service destino
gcloud beta run domain-mappings create \
    --service=<nuevo-service> \
    --domain=altlegal.paralegal.technology \
    --region=<nueva-region> --project=altlegal-ai

# 3. Actualizar el CNAME en GoDaddy si la región nueva da un destino distinto
# 4. Esperar re-provisionamiento del cert (~15 min)

Borrar mapping permanentemente

gcloud beta run domain-mappings delete \
    --domain=altlegal.paralegal.technology \
    --region=europe-west1 --project=altlegal-ai

Quita el dominio del service; el cert managed se descarta. Borrar también el CNAME en GoDaddy.

Backups Cloud SQL — visión general

La instancia altlegal-ai-pg tiene 4 mecanismos de respaldo combinados que cubren distintos escenarios de recovery:

Listar backups disponibles

gcloud sql backups list \
    --instance=altlegal-ai-pg \
    --project=altlegal-ai

Devuelve una tabla con columnas ID, WINDOW_START_TIME, ERROR, STATUS, INSTANCE. El ID es el handle que necesitas para hacer restore. Identifica el backup del día anterior por WINDOW_START_TIME.

PITR — Point-in-Time Recovery

Habilitado el 2026-06-06. Cloud SQL archiva transaction logs continuamente — permite restaurar a cualquier timestamp dentro de los últimos 7 días con granularidad de segundo.

Restore a punto exacto en tiempo (NO destructivo — crea instancia nueva):

gcloud sql instances clone altlegal-ai-pg altlegal-ai-pg-restored \
    --point-in-time='2026-06-06T03:45:00Z' \
    --project=altlegal-ai

Tras crear el clone, validar contenido, exportar lo necesario, y eliminar el clone. Costo del clone: ~$1/día mientras vive.

Costo PITR: ~$1-2 USD/mes adicionales (transaction log storage). Habilitado con:

gcloud sql instances patch altlegal-ai-pg \
    --enable-point-in-time-recovery \
    --project=altlegal-ai

Cross-region weekly export DR

Cloud Scheduler dispara semanalmente un export gestionado por Cloud SQL Admin API hacia un bucket multi-region EU. Sobrevive un outage completo de Madrid.

Verificar próximo fire + última ejecución:

gcloud scheduler jobs describe altlegal-ai-pg-weekly-export \
    --location=europe-west1 --project=altlegal-ai \
    --format='value(state,scheduleTime,lastAttemptTime,status)'

Trigger manual (fuera de schedule):

gcloud scheduler jobs run altlegal-ai-pg-weekly-export \
    --location=europe-west1 --project=altlegal-ai

Listar versiones disponibles en el bucket EU:

gcloud storage ls --all-versions -l gs://altlegal-ai-backups-eu/

Snapshot filtrado manual

Script scripts/backup-prod-snapshot.sh genera un pg_dump filtrado que excluye chat_sessions, audit_events, llm_call_log, notifications. Útil para sync local↔prod o pre-flight antes de cambios riesgosos.

# Snapshot + upload a GCS Madrid:
bash scripts/backup-prod-snapshot.sh --gcs-bucket=altlegal-ai-backups

# Sólo local:
bash scripts/backup-prod-snapshot.sh --output=/tmp/snapshot.sql.gz

Atómico: TRUNCATE + INSERT envueltos en una sola transacción (fix del incidente 2026-05-26). Si el import falla a mitad, rollback automático — la DB NO queda vacía.

Restore (rollback) — dos rutas

Ruta A — restore in-place (DESTRUCTIVO)

gcloud sql backups restore <BACKUP_ID> \
    --restore-instance=altlegal-ai-pg \
    --project=altlegal-ai

Ruta B — restore a instancia temporal (NO destructivo, recomendado)

Crea una nueva instancia con los datos del snapshot. Te conectas, copias lo que necesites, lo importas a la instancia productiva. Cuando terminas, borras la temporal.

# 1. Crear instancia temporal desde el backup
gcloud sql backups restore <BACKUP_ID> \
    --restore-instance=altlegal-ai-pg-snapshot \
    --project=altlegal-ai

# 2. Conectarse vía Cloud SQL Auth Proxy
gcloud sql connect altlegal-ai-pg-snapshot \
    --user=postgres \
    --database=legal_ai \
    --project=altlegal-ai

# 3. Exportar las tablas / filas que necesitas. Ejemplo:
#    pg_dump -h ... -U postgres -d legal_ai \
#      -t tenant_altlegal.casos_de_uso \
#      --data-only --column-inserts > restore.sql
#    Luego en la productiva:
#    psql -h ... -U postgres -d legal_ai < restore.sql

# 4. Cuando terminas, eliminar la temporal para no acumular costo
gcloud sql instances delete altlegal-ai-pg-snapshot \
    --project=altlegal-ai \
    --quiet

Configuración de backups

Verificar config actual:

gcloud sql instances describe altlegal-ai-pg \
    --project=altlegal-ai \
    --format='yaml(settings.backupConfiguration)'

Modificar horario o retención:

# Cambiar la hora del backup diario (UTC)
gcloud sql instances patch altlegal-ai-pg \
    --backup-start-time=03:00 \
    --project=altlegal-ai

# Cambiar la retención (cuántos backups guardar antes de rotar)
gcloud sql instances patch altlegal-ai-pg \
    --retained-backups-count=14 \
    --project=altlegal-ai

# Deshabilitar backups (NO recomendado)
gcloud sql instances patch altlegal-ai-pg \
    --no-backup \
    --project=altlegal-ai

Verificación periódica recomendada

Gaps reconocidos (no implementados, evaluar trigger):

• Alertas Cloud Monitoring sobre backup failure — gratis, no implementado todavía.
• Aumentar retención automated de 7 a 30 días — ~+$1-2/mes, sólo si compliance lo pide.
• Read replica cross-region (HA caliente con failover automático) — ~+$27-30/mes, over-engineered hoy.