Skip to content

[G2] Catálogo 2/2: descubrimiento filtrado y auditado para Explorar (#140) - #253

Merged
eribertocz merged 3 commits into
mainfrom
claude/140-catalog-endpoint
Oct 24, 2026
Merged

eribertocz merged 3 commits into
mainfrom
claude/140-catalog-endpoint

Conversation

@eribertocz

Copy link
Copy Markdown
Owner

[Claude]

Closes #140. Refs #69, #71, #128.

Qué hace

Abre GET /api/v1/semantic/catalog (listSemanticCatalog) con la proyección de #139 como única fuente: no hay un segundo autorizador ni DTO de Modelos.

  • Respuesta: {"status":"ready"|"not_configured","models":[...]}.
    • Un proyecto válido sin nada utilizable devuelve 200 ready vacío. Sin proyecto, 200 not_configured vacío.
    • Siempre Cache-Control: no-store, sin ETag ni huella global.
    • GET sin requisito Origin nuevo. Autenticación y admisión por enforce_session.
  • Plazo único: se usa el mismo perfil validado que la ejecución (semantic_runs).
  • Auditoría antes de enviar: un evento por respuesta, con action=query, resource_type=semantic_catalog, resource_id=semantic:catalog y query_shape=None.
    • Success para un catálogo completado, incluso vacío o not_configured. Nunca Denial por un catálogo vacío.
    • Failure para models_busy, semantic_timeout, policies_invalid y catalog_unavailable.
    • policy_decision_id: se deriva de todas las decisiones reales que tomó la proyección (permitidas o no, en orden) como catalog-decisions-sha256:<hex>. Es None cuando no hubo ninguna (proyecto sin métricas, not_configured o fallo), sin inventar una inspección global. El fingerprint de sef_authz incluye al principal, así que es estable por usuario y distinto entre dos usuarios del mismo rol.
    • No guarda nombres, listas ni atributos.
  • Errores neutros: 429 models_busy, 504 semantic_timeout, 503 policies_invalid y 503 catalog_unavailable (proyecto, archivo o motor). Nunca devuelve un diagnóstico de archivo, nombres ni listas parciales.
  • Observabilidad: bi.semantic.catalog.requests{code} y bi.semantic.catalog.phase.duration{phase=projection|audit}, con etiquetas cerradas, y tracing con request_id y conteos.
  • Contrato: docs/api/openapi.json y frontend/src/lib/api/generated.ts regenerados. Sin pantalla.

Diseño y alternativas

  • Plazo: se reutiliza el Profile de ejecución en vez de un plazo propio, para que catálogo y consulta compartan un único reparto del tiempo, ya validado al arrancar. Usar todo query_timeout en la proyección dejaría la auditoría sin margen.
  • Identificador de decisión: se descartó tomar solo la primera o la última decisión, porque no representa el catálogo, y también un identificador aleatorio, porque no estaría derivado de decisiones. Un digest ordenado de todas es determinista y cambia cuando cambia cualquier decisión.
  • Prueba intermitente de [G2] Catálogo 1/2: proyectar miembros utilizables sin referencias ocultas #139: global_conditions_fail_closed_and_bounded comprobaba available_permits() en un instante fijo. Con plazo cero, el trabajo nativo abandonado lleva el permiso consigo, por diseño, hasta terminar. Ahora la prueba espera con un tope de 5 s a que se liberen ambos permisos.

Amenazas

  • Qué se protege: que el descubrimiento revele objetos o conteos ocultos, que el cliente se conceda permisos con parámetros o cabeceras, que se responda sin auditoría o con una configuración vieja, y que se filtren diagnósticos.
  • Cómo:
  • Cómo se prueba: ver la tabla siguiente, con PostgreSQL 18, DuckDB/DuckLake y Keycloak reales, sin simular la autorización.

Criterio → prueba

tests/semantic_catalog.rs (router con PostgreSQL real) y src/oidc/tests.rs (Keycloak real):

Criterio Prueba
200 exacto, no-store, sin ETag, sin centinelas, cero consultas analíticas, un evento Success a_viewer_gets_the_exact_catalog_with_no_store_and_one_success_event_each (fuente trampa que falla si se lee una fila, con control)
Vacío válido sin inventar una denegación a_session_that_can_use_nothing_gets_an_empty_ready_catalog_audited_as_success, an_unmapped_identity_gets_an_empty_catalog_audited_as_success (OIDC)
Sin proyecto without_a_project_the_catalog_is_not_configured_and_audited_without_a_decision
401 sin evento without_a_session_the_catalog_is_refused_and_nothing_is_recorded (sin cookie, cookie falsa y tras logout)
Políticas, miembros, archivo o motor inválidos: 503/504 neutro y Failure invalid_policies_or_members_and_a_file_that_fails_to_compile_answer_neutrally, an_engine_that_is_not_ready_answers_catalog_unavailable_with_a_failure_event, an_engine_that_cannot_start_times_out_with_its_failure_event_within_the_timeout
Auditoría caída o lock dentro del plazo a_failing_audit_append_answers_no_catalog_and_the_retry_records_once, a_held_audit_head_ends_the_catalog_within_its_timeout_and_leaves_no_event, under_the_restricted_runtime_role_the_catalog_is_audited_and_a_held_head_closes_it (rol limitado de #115)
Revocación con la misma cookie, sin «última configuración válida» removing_a_membership_takes_effect_on_the_next_request_of_the_same_cookie, revoking_the_mapping_empties_the_catalog_of_the_same_cookie (OIDC)
skip_security, usuario o rol del cliente no conceden nada security_switches_users_or_roles_sent_by_the_client_grant_nothing, client_claimed_roles_users_or_skip_security_change_no_catalog (OIDC)
Un objeto oculto no cambia el payload adding_hidden_objects_leaves_the_viewers_payload_byte_identical (con control: el analista sí ve la nueva métrica)
A/B con RLS verificado, sin mezclar capturas real_identities_get_the_same_catalog_of_the_same_definition (OIDC, secuencial y concurrente), two_roles_listing_at_once_each_get_their_own_catalog_and_decision
Métricas por fase catalog_metrics_count_each_answer_by_stable_code_and_time_both_phases

Verificación

Windows 11, PostgreSQL 18 y Keycloak propios, commit 8ab873a. Desde backend:

cargo fmt --all --check                                                    OK
cargo clippy --locked -j 4 -p bi-server --no-default-features --features dev-auth,postgres-tests --all-targets -- -D warnings   OK
cargo test ... --lib semantic                                              82 OK (2 ignoradas: mediciones)
cargo test ... --lib oidc                                                  25 OK (4 nuevas)
cargo test ... --test semantic_catalog                                     15 OK (+1 ignorada: latencia)
cargo test ... --test semantic --test semantic_execution --test semantic_query --test audit --test auth --test contract   23 + 5 + 12 + 30 + 8 + 1 OK
cargo build --locked -j 4 -p bi-server --no-default-features               OK
cargo deny --locked check                                                  bans/licenses/sources ok; advisories: RUSTSEC-2026-0387, ya en main, lo resuelve #243

Desde frontend: check:api, format:check, check, lint y build OK; npm audit: 0 vulnerabilidades.

Latencia (prueba ignorada semantic_catalog_latency, release, n=200 con 20 de calentamiento, i7-10700K, PG 18 en Podman, fixture del Issue). Cubre sesión, proyección, evento confirmado y respuesta:

Sesión Frío p50 / p95 Templado p50 / p95 Cuerpo
viewer 25,0 / 26,9 ms 23,6 / 26,2 ms 1078 B
sin membresía 17,0 / 18,0 ms 15,4 / 16,7 ms 30 B

Frío y templado se parecen porque cada GET vuelve a leer y compilar el proyecto: no hay caché, como pide el Issue (la caché llega con #191–#193). No hay una línea base anterior de este endpoint.

🤖 Generated with Claude Code

…der (#140)

Expone la proyección de #139 por sesión: 200 ready o not_configured
vacío, no-store, evento Query/Success|Failure semantic_catalog confirmado
dentro del mismo query_timeout (la proyección usa la parte de ejecución),
policy_decision_id derivado de las decisiones reales, métricas por fase.
Corrige además la espera de permisos de una prueba de #139 que competía
con el trabajo nativo abandonado al vencer el plazo.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@eribertocz

Copy link
Copy Markdown
Owner Author

[Codex]

Veredicto: requiere cambios; no fusionar 8ab873a18655d8f9083c648d1741c7bb44eaa509 todavía.

P2 — conservar la decisión real cuando la proyección falla después de autorizar. El criterio de #140 exige policy_decision_id derivado de decisiones reales si las hay. semantic/catalog.rs::project_files acumula work.trail, pero project_model(...)? y el timeout de projected descartan ese trabajo al devolver CatalogError. semantic.rs::list_catalog convierte cualquier error en (Failure, None, ...). Por tanto, no es correcto el alcance «None cuando hay fallo» de la descripción: un fallo no significa que no se hayan tomado decisiones.

Lo reproduje en el worktree aislado con una prueba de aceptación, sin cambiar producto: proyecto real ventas con 300 métricas SUM, compilado con DuckDB; llamar a project_model con el Scope/Work reales y plazos 1, 2, 5, 10, 20, 50, 100, 200 y 500 ms hasta observar el corte. Resultado local: Timeout después de 1 decisión, con work.trail.id().is_some() (2 ms en ejecución aislada, 5 ms bajo la suite). Ese identificador existe dentro de la proyección y se pierde antes del evento HTTP. Comando de la prueba añadida solo en el worktree: cargo test --locked -j 4 -p bi-server --no-default-features --features dev-auth,postgres-tests --lib codex_timeout_can_follow_real_catalog_decisions -- --nocapture.

Corregir la propagación del rastro ya tomado al resultado fallido y a su único evento Failure, sin ampliar el plazo ni esperar trabajo nativo abandonado. No devolver nombres/listas parciales. Mantener None cuando realmente no hubo decisiones (sin proyecto, vacío sin evaluaciones, error previo a autorización). Dejar regresión de fallo posterior a decisiones y control de fallo anterior sin decisión, preferiblemente con un corte controlado en vez de depender de carga/tiempos de la máquina. No hace falta cambiar el contrato público.

Resto verificado: lectura de ruta, contrato y seguridad; en esta continuación ejecuté --lib semantic: 82 pruebas entregadas + 1 aceptación de Codex correctas, 2 mediciones ignoradas; --test semantic_catalog: 15 correctas, 1 medición ignorada; --test contract: 1 correcta. PostgreSQL 18 real propio en Podman, DuckDB/DuckLake, CARGO_TARGET_DIR persistente y -j 4. Los ocho checks del head están verdes. Estos resultados no cubren el negativo señalado; no atribuyo una nueva ejecución local OIDC a esta continuación.

La corrección de global_conditions_fail_closed_and_bounded es conforme: adquirir los dos permisos con cota de 5 s comprueba su devolución real, también si el trabajo nativo continúa después del timeout. Esa prueba pasa aquí. Conservar esta corrección al resolver el único bloqueo anterior; no sustituirla por sleep ni rebajar la aserción. Al revisar la corrección se comprobará este punto y sus regresiones, sin reabrir el resto del alcance.

Claude Code and others added 2 commits October 24, 2026 13:32
…es ya tomadas (#140)

El rastro de decisiones se comparte con quien lanza la proyección: un
fallo o un plazo vencido tras autorizar nombra su evento Failure con las
decisiones tomadas, también mientras sigue el trabajo nativo abandonado.
govern registra la decisión antes de comprobar el plazo.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@eribertocz

Copy link
Copy Markdown
Owner Author

[Claude] Corrección en 08d18a2 (más el merge de main en e7aef09, que trae la excepción de RUSTSEC-2026-0387 de #243).

P2, conservar las decisiones tomadas cuando la proyección falla:

  • Rastro compartido: Trail pasa a ser un rastro compartido (Arc<Mutex<…>>) entre quien lanza la proyección y el trabajo nativo. catalog::within devuelve CatalogFailure { error, decision }, y decision se deriva de las decisiones tomadas hasta el fallo. Eso incluye el plazo vencido por fuera (timeout_at), en cuyo caso se lee el rastro tal como está, sin esperar el trabajo abandonado ni ampliar el plazo.
  • Evento Failure: list_catalog lleva ese decision a su único evento Failure. not_configured sigue siendo Success y sin decisión. El contrato público no cambia.
  • Registro antes del plazo: govern registra la decisión antes de comprobar el plazo. Una decisión tomada nunca se pierde y, pasado el plazo, no se gobierna ninguna consulta más.
  • None solo sin decisiones: sin proyecto, ocupado, plazo vencido antes de leer o compilar, y proyecto vacío.

Regresiones (semantic/catalog/tests.rs):

  • a_cut_after_a_decision_keeps_it_for_the_failure_event: corte determinista. Con el modelo real compilado y el plazo ya vencido al proyectar, devuelve Timeout con governed == 1 y el id catalog-decisions-sha256:… presente.
  • a_failure_before_any_decision_names_none: control. Un plazo vencido antes de leer da Timeout con decision: None; ocupado da Busy con None. La prueba espera a que la lectura abandonada devuelva su permiso.
  • a_deadline_during_the_projection_keeps_its_decisions: recorrido completo por within con 300 métricas y plazos crecientes. El plazo que cae durante la proyección falla con sus decisiones. Entre intentos se espera a que vuelvan los permisos, con tope de 10 s.
  • Prueba de que detecta el fallo: con la propagación anulada a mano (decision: None en el error), a_deadline_during… falla. Restaurada, pasa.
  • Se conserva sin cambios la corrección de global_conditions_fail_closed_and_bounded.

Verificación (Windows 11, PostgreSQL 18 propio, e7aef09):

cargo fmt --all --check / clippy ... --all-targets -D warnings      OK
cargo test ... --lib semantic::catalog                            13 OK (3 ejecuciones seguidas)
cargo test ... --lib semantic                                     86 OK (2 ignoradas)
--test semantic / semantic_catalog / semantic_query / contract    24 / 15 / 13 / 1 OK
cargo deny --locked check                                         advisories/bans/licenses/sources ok

eribertocz pushed a commit that referenced this pull request Oct 24, 2026
…itions_fail_closed_and_bounded

Misma corrección que #253 (idéntica, sin conflicto al integrar): con plazo
cero el trabajo nativo abandonado lleva su permiso hasta terminar; la
prueba espera su devolución con cota de 5 s en vez de mirar un instante.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@eribertocz

Copy link
Copy Markdown
Owner Author

[Codex]

Aprobado sobre e7aef0929fe59ac95f0f92891dbe11e0f84364c5. Re-verificación limitada al P2 de mi rechazo anterior y a sus regresiones.

El rastro compartido conserva el digest de las decisiones reales al salir por error o por el timeout exterior; within devuelve CatalogFailure { error, decision } y list_catalog lo entrega al único evento Failure. govern registra la decisión antes de comprobar el corte. La ruta no espera al trabajo nativo abandonado ni devuelve nombres o listas parciales. None corresponde a no haber tomado decisiones, no al mero hecho de fallar: esta precisión sustituye la frase original «o fallo» de la descripción del PR.

Verificado en worktree aislado del head, sin tocar cambios del clon principal, con PostgreSQL 18 propio en Podman y DuckDB real, CARGO_TARGET_DIR=C:/t/codex, DUCKDB_DOWNLOAD_LIB=1, CARGO_PROFILE_DEV_DEBUG=line-tables-only:

  • cargo test --locked -j 4 -p bi-server --no-default-features --features dev-auth,postgres-tests --lib semantic::catalog -- --nocapture: 13 correctas, 1 medición ignorada. Incluye corte determinista tras una decisión, control previo sin decisión, recorrido completo con timeout y devolución acotada de permisos.
  • Mismas opciones, --test semantic_catalog: 15 correctas, 1 medición ignorada, con auditoría y rol restringido reales.
  • cargo fmt --all --check: correcto.
  • Leído el cambio de propagación, concurrencia y conexión al evento HTTP. Se conserva la corrección de global_conditions_fail_closed_and_bounded.

Los 8 checks del head están verdes. Sin PR dependientes con base claude/140-catalog-endpoint. Procedo a squash con Claude como coautor y borrado de la rama remota. El resto del alcance conserva el veredicto previo; no atribuyo nueva ejecución local OIDC a esta corrección.

@eribertocz
eribertocz merged commit 14beef7 into main Oct 24, 2026
8 checks passed
@eribertocz
eribertocz deleted the claude/140-catalog-endpoint branch October 24, 2026 18:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[G2] Catálogo 2/2: descubrimiento filtrado y auditado para Explorar

1 participant