# Radar · Protocolo de inteligencia de producto 1.1 · API 0.4 Full

## Responsabilidad

El agente asume la investigación y evaluación. No termina con «revisa los anuncios y decide si son comparables». Entrega un dictamen ejecutivo: cuál es el grupo, por qué una alternativa se incorpora, qué queda fuera, qué acción permite la evidencia y qué trabajo asume el sistema cuando faltan datos. La certeza absoluta no se promete: desconocido no es falso; sin oferta no es ocupado; fotos no equivalen a inspección presencial.

La pantalla `/comparar` ofrece síntesis, gráficos y dictámenes; sus fuentes están disponibles como respaldo, no como tarea para el propietario. `POST /api/v1/investigaciones` inicia la investigación alojada con resultado privado y cobertura explícita. `POST /api/v1/encargos` prepara un encargo para un agente externo. `POST /api/v1/analisis` valida y calcula sobre evidencia aportada por el agente externo. No almacena estudios, no visita fuentes en esa llamada y no acredita autenticidad por validar el formato. La interfaz identifica explícitamente cualquier alternativa de cálculo local. Ver [operacion.md](/agentes/operacion.md).

## Cinco capas y entregas especializadas

1. **Identidad y demanda de la estancia.** Resolver inmueble, unidad, capacidad natural, ocupación máxima, distribución de camas/baños y propósito del viaje. Identificar el mismo inmueble en distintos canales; variantes no son competidores distintos.
2. **Producto y lectura visual.** Un investigador recorre portada, dormitorios, baños, cocina, áreas comunes y exteriores. Otro contrasta amenidades, ubicación y restricciones. Confirmar calefacción de piscina explícita; la calefacción ambiental no cuenta. Registrar afirmaciones del proveedor, observaciones visuales y ausencias por separado.
3. **Experiencia y reputación.** Revisar reseñas DEL INMUEBLE, número, fechas y patrones de ruido/limpieza/servicio. No transferir el rating del anfitrión. No inventar valoración de una casa nueva. Fotografías, composición y descripción evalúan presentación; no certifican material, mantenimiento real o lujo.
4. **Oferta comparable.** Misma estancia, moneda, adultos/niños, casa completa, desayuno o extras si aplica, total con impuestos y cargos. Separar garantías y contingencias. Conservar cancelación por hitos y plan. Si no hay precio utilizable, el inmueble puede ser referencia cualitativa, pero no referencia de tarifa.
5. **Revisión y dictamen.** Contrastar contradicciones y aplicar reglas. El precio nunca determina categoría o calidad. No transformar la brecha aritmética en descuento sugerido ni inventar el valor monetario de una amenidad. La recomendación debe considerar producto, términos, demanda y ritmo de reservas; si faltan, no afirmar tarifa óptima.

## Taxonomía extensible (investigar, no completar por intuición)

| Dominio | Campos de investigación |
|---|---|
| Identidad | inmueble, URL canónica, canal, tipo de unidad, administrador, duplicados, unidad completa/compartida |
| Distribución | recámaras, camas por tipo, baños completos/medios, baños privados, sofá cama, colchones, capacidad natural, capacidad máxima, áreas compartidas |
| Agua y exterior | piscina privada/compartida, calefacción explícita, cargo de calefacción, temporada, tamaño documentado, jacuzzi, patio, rooftop, asador, comedor exterior |
| Microubicación | zona declarada, referencia caminable, distancia fuente, playa/centro/malecón, acceso, pendiente/escaleras, ruido de entorno, vistas reales vs texto genérico |
| Acabados | estilo, coherencia, carpintería, superficies, baños, iluminación, mobiliario, desgaste visible, limitación de foto; material certificado vs apariencia |
| Equipamiento | cocina, lavandería, climatización ambiental, Wi-Fi declarado/medido, estacionamiento tipo/capacidad, bicicletas, equipo playa, blackout, trabajo, entretenimiento |
| Experiencia | check-in/out, atención, limpieza, reposición, mantenimiento, depósito, reglas, mascotas, accesibilidad, cámaras declaradas, restricciones relevantes |
| Reputación | rating y escala originales, cantidad, fecha, inmueble vs anfitrión, temas repetidos, incidencias, contradicciones, muestra suficiente/pequeña |
| Presentación | portada real, cobertura de galería, consistencia fotográfica, encuadres, claridad descriptiva, promesas verificables; sin confundir marketing con calidad física |
| Oferta | fechas, noches, huéspedes, moneda, alojamiento, limpieza, impuestos, cargos, descuentos, plan, política de cancelación, garantía aparte, antigüedad de captura |
| Evidencia | URL pública, momento de consulta, tipo hecho/juicio/desconocido, captura o archivo, contradicción, evaluador y trabajo pendiente |

No todos los campos son obligatorios para todo tipo de inmueble. Este piloto es de casas enteras con piscina en MXN para adultos; no presentar el mismo esquema como evaluación completa de hoteles o alojamiento compartido.

## Reglas del motor actual

Siete ejes ejecutivos: `space`, `thermal`, `location`, `views`, `finish`, `amenities`, `rest`. Relación: `match`, `stronger`, `weaker`, `different`, `unknown`. Cada eje lleva evidencia textual y URL. El número de ejes `match` es una cuenta auditable, no un porcentaje de certeza ni puntuación de lujo.

- **Otro segmento:** unidad, recámaras o capacidad no corresponden; o piscina expresamente no climatizada frente a sujeto climatizado. No implica mala calidad.
- **Pendiente:** falta acreditar climatización, ubicación o evaluación visual. No acredita equivalencia. Solo la falta de climatización admite la excepción contextual descrita abajo; las demás carencias esenciales impiden incorporar el producto a la selección tarifaria Radar.
- **Equivalente:** siete ejes afines documentados. Aun así revisar los términos de oferta por separado.
- **Superior:** dos o más ventajas y el resto de ejes afines o ventajosos; no basta un precio mayor ni estilo más moderno.
- **Menor equipamiento:** desventajas documentadas en cuatro o más ejes, sin ventajas acreditadas; no usar antigüedad o estilo como penalización automática.
- **Similar:** núcleo compatible y evaluación visual suficiente, con diferencias expresas. Es una referencia cualitativa; la posibilidad de comparar precios depende de la oferta.

Precio contextual elegible: categoría equivalente/similar/superior o la excepción de climatización pendiente, misma estancia, ocupación y moneda, total con impuestos y cargos completos, y captura propia y comparable de hasta 24 horas. El rango principal, separado de este contexto, admite exclusivamente la categoría equivalente. Las ofertas caducadas permanecen históricas, pero salen del grupo vigente. Guardar cada variante y su fecha; no renovar un precio por volver a evaluar fotos. Con menos de tres propiedades distintas elegibles no se declara referencia tarifaria suficiente. Tres es un umbral operativo de piloto, no garantía estadística ni muestra representativa del mercado. No se calcula valor justo ajustado por atributos ni pronóstico sin un modelo y validación adicionales.

**Excepción contextual de climatización:** un perfil conserva `pending`, pero puede aportar contexto si la calefacción propia tampoco está acreditada o está expresamente ausente, y sigue sin acreditarse la calefacción propia o comparable. Requiere misma unidad, recámaras propias conocidas y recámaras comparables iguales o una adicional, capacidad suficiente, privacidad de piscina confirmada e igual, sin incompatibilidad de micromercado, revisión visual y ubicación/acabados documentados. Los ejes de distribución, piscina, ubicación o equipamiento marcados `different` impiden esta excepción; por ejemplo, una piscina cerrada no equivale a una piscina disponible. Una diferencia documentada `weaker` se conserva y explica. Si la propia sí tiene calefacción, una referencia sin calefacción acreditada no entra por esta vía. No convertir `null` en `false` ni en `match`: el informe indica «Comparación descriptiva; equivalencia pendiente» y advierte que la calefacción desconocida podría explicar diferencias de precio.

## Entrega e importación

Entregar `{ "study": {...}, "assessment": {...} }` por `POST /api/v1/analisis` o importarlo en `/comparar/#investigacion`. El contrato HTTP completo está en [/openapi.json](/openapi.json). Son hasta 512 KiB de JSON, 50 observaciones y 21 perfiles contando la propiedad propia. La respuesta lleva `independentlyVerified:false`, `persisted:false` y datos normalizados sin campos extra.

- `study`: esquema [browser-observations-1](/agentes/observaciones.md). Conserva el total, políticas y momento real observado.
- `assessment`: `schemaVersion:"radar-assessment-1"`, `studyId` igual al `study.id`, `profiles`; `reviewedAt` y `selectionScope` son opcionales. Si se omite la evaluación, las propiedades quedan pendientes y no se acreditan automáticamente por su precio.
- Cada perfil: `propertyId` igual al del estudio, `title`, `source` público HTTPS, `reviewedAt`, `unit`, `bedrooms`, `capacity`, `privatePool:true|false|null`, `heatedPool:true|false|null`, `visualReview:boolean`, `conclusion`; `subtitle` es opcional.
- `axes`: los siete ejes, cada uno con `relation`, `evidence` y `source` HTTPS. No marcar match sin evidencia.
- `photo`: portada original con `src`, `alt` editorial fiel y `source`. El piloto alojado acepta imágenes guardadas por el editor en `/assets/comparables/`; la importación no sube fotos y no acepta URLs arbitrarias para rastrear al usuario. Si aún no existe un recurso aprobado, omitir `photo`; el análisis puede continuar. No reutilizar la fotografía del ejemplo para otra propiedad. La falta de evidencia visual sí se documenta en `visualReview` y en los ejes correspondientes.
- Síntesis: `zone`, `conclusion`, `watch`, `review:{label,detail,verifiedCount}`, `visual`, `conditions`.
- Las tareas propuestas se explican en el informe externo con su estado real. La API no ejecuta acciones aportadas en el JSON y elimina campos extra como `actions` o `audit`; no simular agentes que ya estén trabajando si no se han despachado.

Ejemplo de precios: [/data/consultas/altamar-2026-11-05-full.json](/data/consultas/altamar-2026-11-05-full.json)
Evaluación: [/data/evaluaciones/altamar-full.json](/data/evaluaciones/altamar-full.json)

## Selección Full

Hasta 20 propiedades únicas seleccionables. En el caso Altamar, cohorte estructural de tres recámaras; grupo ampliado de cuatro, con la diferencia explícita. Esta agrupación por recámaras no debe confundirse con el rango principal equivalente. Seis recámaras o tipologías distintas corresponden a otro segmento; la piscina compartida o no climatizada se excluye cuando contradice la piscina privada o climatizada acreditada de la propiedad propia. Dos piscinas expresamente compartidas pueden ser compatibles, sin acreditar por ello calefacción ni equivalencia. Una capacidad publicada como «más de 16» es un límite inferior, no un máximo de 17.

Radar propone su cohorte por producto. El usuario puede seleccionar o quitar candidatos; el grupo personal recalcula rango, mediana y brecha, pero no altera el dictamen de Radar. `buildExecutive(study, assessment, now, {selectedPropertyIds, cohort})` acepta hasta 20 IDs. Una lista vacía no restaura silenciosamente los valores originales. El navegador guarda la selección por estudio en ese dispositivo; no implica cuenta o sincronización.

Una referencia cotizada permite mostrar una brecha descriptiva con advertencia de muestra limitada. Menos de tres no activa suficiencia; tres tampoco representan todo el mercado. Los precios completos conservan cancelación y extras: no son productos económicamente idénticos. `comparableTotalComplete:false` excluye cargos esenciales no resueltos incluso de la cohorte personal. `privatePool` y `heatedPool` admiten null. `unavailable`, `blocked` y `not_checked` conservan `total:null` y nunca se confunden con ocupación.

## Caso ampliado de Altamar

20 candidatos únicos, 8 afines por producto y una referencia afín cotizable en esta captura: Marea Ocean View, $80,733.21 frente a $72,854 de Altamar, 9.8% menos. La diferencia de resort frente a Centro, los servicios y la cancelación se explican. No es un promedio de mercado ni una recomendación automática de tarifa. Las cuatro propiedades anteriores conservan sus horas originales; las 16 nuevas tienen la hora de guardado de su lectura de navegador. Al expirar 24 horas salen del cálculo vigente. Los archivos originales continúan publicados como históricos.


## Contrato Observatory 0.3: equivalentes, contexto y estados

El **rango principal** usa exclusivamente `category:"equivalent"`, total completo para la misma estancia, ocupación y moneda, impuestos y cargos resueltos y vigencia admitida de la referencia propia y comparable. En el motor se consulta mediante `primaryEligible` y `primaryBenchmark`. No mezclar en este rango similares, superiores, inferiores, pendientes ni otros segmentos.

La **referencia contextual** (`contextEligible`, `contextBenchmark`) mantiene la comparación descriptiva de la selección Radar o la cohorte personal. Puede mostrar mediana y brecha, siempre identificadas como contexto. Elegir un candidato manualmente no acredita equivalencia. `benchmark` se conserva como compatibilidad para este contexto; no interpretarlo como rango principal.

**Suficiencia del informe autónomo:** `completed` exige oferta propia completa y vigente y al menos tres propiedades distintas elegibles en el rango principal o en la selección contextual **Radar**. Al finalizar se recalcula desde las observaciones y perfiles normalizados; no basta un contador de precios ni una cohorte personal. Si solo alcanza suficiencia contextual, el mensaje es «La comparación descriptiva está lista; la equivalencia sigue pendiente», las clasificaciones no cambian y el diagnóstico tarifario conserva **ESPERAR MÁS EVIDENCIA**. Con menos de tres referencias elegibles se entrega `partial` con las observaciones y el análisis disponibles. Completar este informe descriptivo no acredita equivalencia, demanda, representatividad del mercado ni aceptación comercial del servicio.

Si no hay equivalentes utilizables, el diagnóstico tarifario es **ESPERAR MÁS EVIDENCIA**. Conservar la tarifa durante la revisión evita un cambio no respaldado; no certifica un precio justo. Incluso con varias referencias equivalentes, el motor no autoriza variaciones automáticas sin señales adicionales de demanda y condiciones comerciales. No inventar un porcentaje de confianza.

En Altamar hay cero equivalentes acreditados. Marea y su brecha de 9.8% son una referencia contextual de la captura original, con diferencias de resort, ubicación y servicio. No presentarla como un rango del mercado ni mantenerla vigente al caducar.

**Cobertura:** distinguir «Consulta documentada», «Sin consulta documentada», una consulta efectivamente fallida y una oferta sin disponibilidad. La ausencia de Booking/Expedia en este estudio no demuestra que esos canales no respondieron. Las observaciones y planes no equivalen al número de inmuebles. La evaluación cualitativa y la recarga de pantalla no renuevan `observedAt`.

**Navegación:** `/comparar/#resumen`, `#competidores`, `#mercado` y `#investigacion` son las cuatro secciones visibles. Se conservan `#precios`, `#ubicacion` y `#ubicaciones` hacia Mercado; `#recomendaciones` abre acciones desde Resumen; `#seleccion` va a Competidores; `#metodo` y `#agent-console` van a Investigación, abriendo la consola en este último caso.

Las acciones de la interfaz son un flujo local de revisión: aprobación, nota de ajuste, postergación o descarte. No son cambios aplicados a OHOS, no despachan investigadores y no crean una programación activa. La herramienta de encargo y la importación siguen disponibles para un agente externo; debe traer evidencia auténtica sin sugerir que la interfaz por sí sola realizó una nueva consulta.