09 — Reglas de validación y catálogo de errores

ID: GS-VAL-001 · Versión: 0.2.0 Contratos relacionados: contracts/test-vectors/location_samples.json, contracts/test-vectors/ids.json, enum ErrorCode en common.proto, esquema Problem en OpenAPI.

1. Principios

1. Todo dato que llega de un cliente es no confiable y se valida en el servidor, aunque el SDK también lo valide.
2. La validación es pura y determinista (gs-domain): dado el mismo input, el mismo now y la misma política, el mismo resultado.
3. Se falla de forma cerrada: ante duda, rechazar.
4. Un error informa del primer fallo según el orden definido (orden estable = pruebas estables).
5. Los mensajes de error no contienen el valor recibido cuando puede ser sensible (coordenadas, códigos, tokens). Indican el campo y la razón.

2. Reglas generales de REST

2.1 Vocabulario de reason en errores de campo

required, invalid_format, out_of_range, not_finite, too_long, too_short, too_many, not_allowed, unknown_field, invalid_enum, conflict.

Cada error de campo REST: { "field": "<ruta JSON con puntos>", "reason": "<reason>" }.

3. Muestra de ubicación (LocationSample)

3.1 Orden de evaluación y reglas

Las reglas se evalúan en este orden; el primer fallo produce SAMPLE_STATUS_REJECTED, error_code = INVALID_LOCATION y field = la ruta indicada (en stream; en la ingesta HTTP el mismo par field/error_code va en SampleResult).

Normalizaciones (sin error):

• quality.source o quality.motion con un valor numérico desconocido se tratan como UNSPECIFIED.
• En proto3, la "presencia" de latitude, longitude y horizontal_accuracy_m no es distinguible del valor 0; por eso horizontal_accuracy_m = 0 falla la regla 7 y (0, 0) se cubre con la regla 6.

Reglas del SDK antes de enviar (12 §11): convertir velocidades/rumbos negativos de la plataforma en "ausente", normalizar heading == 360 a 0, nunca inventar precisión.

3.2 Resultados no erróneos

• captured_at < now − GS_LOCATION_MAX_EVENT_AGE_MS → SAMPLE_STATUS_IGNORED_STALE (no avanza la secuencia).
• sequence == última aceptada → SAMPLE_STATUS_IGNORED_DUPLICATE.
• sequence < última aceptada → SAMPLE_STATUS_IGNORED_STALE.

3.3 Calidad

• El servidor no modifica quality.
• Si en el futuro el servidor produce datos derivados (F13), los emitirá con kind ≠ MEASURED y nunca sobrescribirá la medición original.

3.4 Tiempo

• now = reloj del servidor en el momento de procesar el lote (un único valor por lote, también usado como received_at de sus muestras aceptadas).
• Bordes: captured_at == now + skew → válido; captured_at == now − max_age → válido (no stale).

4. Algoritmo de aceptación (normativo)

// ILUSTRATIVO en sintaxis; NORMATIVO en orden y semántica.
fn process_publish(conn, msg: PublishLocation) -> PublishAck:
    // 1. Precondiciones del lote (08 §6.4), en el orden de la tabla.
    if let Err(code) = check_batch_preconditions(conn, msg): 
        return PublishAck { session_id, request_error: code, results: [], retry_after_ms }
    now = server_clock.now()
    policy = effective_policy(conn.tenant, session)
    results = []
    last_accepted = None
    max_seq = 0
    for s in msg.samples (en orden):
        // 2. Validación pura (§3.1, reglas 1–16)
        if let Err(field) = validate_sample(s, policy, now):
            results.push(REJECTED(s.sequence, INVALID_LOCATION, field)); continue
        // 3. Antigüedad (§3.2)
        if s.captured_at < now - max_event_age:
            results.push(IGNORED_STALE(s.sequence)); continue
        // 4. Orden (CAS atómico en el almacén efímero, clave seq:{session}:{device})
        match ephemeral.seq_compare_and_set(session, device, s.sequence):
            Duplicate => results.push(IGNORED_DUPLICATE(s.sequence))
            Stale     => results.push(IGNORED_STALE(s.sequence))
            Accepted  =>
                results.push(ACCEPTED(s.sequence))
                last_accepted = Some(s); max_seq = s.sequence
                // 4-bis. Paso de estimación (22 §2.8). Solo si policy.track_estimates_enabled.
                //        La unidad es (device, sequence): una muestra publicada en varias
                //        sesiones conserva la misma sequence y se estima una sola vez.
                est = track_cache.get_or_compute(device, s.sequence,
                          || track.update(track_state(device), s, policy, now))
                bus.publish(loc_topic(session), LocationUpdate{
                    session, member, s, received_at: now, LIVE,
                    estimate: est.for_session(session, member) })
    // 5. Efectos finales
    if let Some(s) = last_accepted:
        if session.snapshot_ttl_seconds > 0: ephemeral.set_snapshot(session, member, update(s), ttl)
        ephemeral.devseq_max(device, max_seq)
        geofence_engine.evaluate(...)   // F11, asíncrono, nunca bloquea
        history_writer.enqueue(...)     // E6, canal acotado, nunca bloquea (24 §2)
    return PublishAck { session_id, request_error: UNSPECIFIED, results, retry_after_ms: 0 }

seq_compare_and_set DEBE ser atómico (script Lua en Redis/Valkey; mutex en memoria). Semántica: si no existe valor previo → Accepted; si seq > prev → guardar y Accepted; si seq == prev → Duplicate; si seq < prev → Stale.

Invariante del paso de estimación (P-E3 / FR-LOC-006). El paso 4-bis nunca modifica ni descarta la muestra s: la estimación viaja en el campo aparte LocationUpdate.estimate, etiquetada FILTERED o MAP_MATCHED. Un fallo del motor de trayectoria (por ejemplo, un conflicto de versión del estado en la ingesta HTTP) no invalida la aceptación: en ese caso estimate va ausente y se incrementa gs_track_state_conflict_total. La aceptación nunca depende de la disponibilidad del filtro.

5. Validación de otros recursos

Los campos y tipos exactos están en OpenAPI. Reglas semánticas adicionales:

5.1 Validación de recursos de la pista E

Error de consentimiento. Si la operación requiere un propósito que el subject no ha otorgado, la respuesta es 403 CONSENT_REQUIRED (nuevo código, §6). Nunca se degrada a PERMISSION_DENIED ni se escribe parcialmente.

6. Catálogo de errores

Fuente del nombre: ErrorCode en common.proto. En REST, code = nombre sin ERROR_CODE_.

Reglas:

• El servidor NO DEBE emitir un code fuera de este catálogo.
• Añadir un código es un cambio menor del contrato (requiere actualizar common.proto, OpenAPI, esta tabla y el mapeo del SDK en el mismo PR).
• INTERNAL nunca incluye detalles internos; el request_id permite correlacionar en logs.

7. Formato de error

• REST: Problem Details, ver 07_REST_API.md §5.
• Stream: StreamError { code, message, retry_after_ms, field, session_id } o PublishAck.request_error / SampleResult.error_code.
• message: inglés, ≤ 200 caracteres, sin valores sensibles. Ejemplo: "latitude out of range", nunca "latitude 91.2 out of range".