# Cellaria - Metodología y registro de claims

Fecha: 14 de julio de 2026

Versión: `cellaria_methodology_v1.0`

Ámbito: producto, datos, informes, demos, ventas y partners

Fuente de UI: `data/cellaria_methodology.json`

## 1. Propósito y alcance

Este documento define cómo Cellaria convierte fuentes on-trade en números y lenguaje publicables. Su objetivo es que cualquier resultado pueda responder, como mínimo, a estas preguntas:

1. ¿Qué mide exactamente?
2. ¿Cuál es el scope y el periodo?
3. ¿Qué unidad cuenta `N`?
4. ¿Cuál es la cobertura y su denominador?
5. ¿Qué registros se excluyeron por matching o calidad?
6. ¿De qué fuente y transformación procede?
7. ¿Qué claim permite la evidencia?
8. ¿Qué no significa el resultado?

La metodología es una guía operativa. No sustituye una revisión legal cuando una salida incluye identidad de establecimientos, detalle sensible, prensa, publicidad, comparaciones directas, datos personales, transferencias internacionales o contratos nuevos.

Los ejemplos de `methodology.html` son didácticos. No son datos reales ni representan el mercado.

## 2. Principios no negociables

### 2.1 Agregado por defecto

Las salidas externas usan buckets, rangos, percentiles, índices o scores. No se publican filas, stock, venta, coste o margen exacto por establecimiento salvo un flujo expresamente autorizado.

### 2.2 Claim proporcional a la evidencia

- Presencia es presencia, no venta.
- PVP de carta no es precio de compra ni margen.
- Una señal parcial sigue siendo parcial.
- Un snapshot no es una tendencia.
- Una asociación no demuestra causalidad.

### 2.3 Identidad protegida

La identidad de un establecimiento requiere simultáneamente:

1. Consentimiento o base contractual documentada.
2. Producto o tier autorizado.
3. Finalidad compatible con la recogida original.
4. Revisión del riesgo de reidentificación y aprobación de producto/legal.

Un `identity_match_confidence` alto no satisface ninguna de estas condiciones por sí solo.

### 2.4 Límites junto al resultado

`N`, cobertura, periodo, fecha de corte, confianza, lineage y caveat deben aparecer cerca del número. No basta con esconderlos en una nota general.

## 3. Secuencia de publicación

Un número debe superar todas las guardas aplicables. El orden operativo es:

1. **Fuente y permiso:** confirmar fuente canónica, finalidad, autorización y canal de salida.
2. **Normalización:** homogeneizar identidad, formato, moneda, fiscalidad, zona horaria y taxonomía.
3. **Matching:** aplicar los umbrales de `identity_match_confidence` registro a registro.
4. **Deduplicación:** eliminar duplicados técnicos y evitar doble conteo entre fuentes.
5. **Muestra y privacidad:** calcular `N`, dominancia y riesgo de reidentificación.
6. **Cobertura:** calcular numerador y denominador para la métrica y el scope exactos.
7. **Periodo y frescura:** validar ventana, fecha de corte y cadencia.
8. **Confianza del claim:** resumir N, cobertura, frescura, lineage, matching, estabilidad y privacidad.
9. **Registro de claims:** comprobar estado, redacción, condiciones y revisión necesaria.
10. **Salida:** publicar con caveat, agrupar, degradar a señal exploratoria o suprimir.

Pseudocódigo normativo:

```txt
if not source_is_usable or not use_is_authorized:
  return unavailable(reason)

rows = normalize(source_rows)
rows = exclude(rows where identity_match_confidence < 0.70)
rows = aggregate_only(rows where 0.70 <= match < 0.85)
rows = allow_specific(rows where match >= 0.85 and identity_is_authorized)
rows = deduplicate(rows)

bucket = build_bucket(rows, scope, period)

if bucket.N < minimum_for(metric) or reidentification_risk(bucket):
  return suppress_or_group("sin muestra suficiente")

coverage = usable_restaurants / covered_restaurants_in_scope
claim_confidence = score(N, coverage, freshness, lineage, match, stability, privacy)

return apply_claim_registry(metric, coverage, claim_confidence, period, channel)
```

## 4. Diccionario metodológico

### 4.1 `p25`, `p50` y `p75`

Los percentiles describen la distribución de PVP normalizados dentro de la muestra cubierta:

- `p25`: el 25% de los valores queda en o por debajo del resultado.
- `p50`: mediana; la mitad queda en o por debajo y la otra mitad en o por encima.
- `p75`: el 75% queda en o por debajo.

Antes del cálculo deben coincidir, como mínimo:

- Moneda.
- Formato y capacidad.
- Tratamiento fiscal conocido o declarado.
- Scope geográfico y de segmento.
- Periodo y fecha de corte.
- Regla de matching.

La unidad de observación debe quedar documentada. Para una referencia y formato, cada restaurante aporta como máximo un PVP usable en la fecha de corte. En benchmarks de categoría con varias referencias, el pipeline debe documentar la ponderación por restaurante para impedir que una carta profunda domine el percentil.

Para publicar un percentil, el pipeline debe guardar la versión del método. La referencia `quantiles_linear_v1` usa interpolación lineal sobre la muestra ordenada; cambiar de algoritmo exige nueva versión y no debe mezclarse en una serie sin recalcularla.

Los percentiles no son mínimo, máximo, precio medio, precio óptimo, precio de compra ni recomendación automática.

### 4.2 Presencia

```txt
presencia = restaurantes distintos con aparición aceptada
            / restaurantes distintos cubiertos en el scope
```

Una aparición aceptada cumple matching, deduplicación, periodo y estado de carta/snapshot. La presencia solo describe aparición observada. No demuestra:

- Venta.
- Rotación.
- Stock o disponibilidad actual.
- Recomendación del restaurante.
- Cuota total de mercado.

Disclaimer mínimo:

> Presencia observada en la muestra analizada. No equivale a ventas ni cuota total de mercado.

### 4.3 Rotación

Rotación es un ritmo agregado de salida o movimiento dentro de fuentes autorizadas. Solo puede derivarse de:

- `sales-events` canónicos y deduplicados.
- Snapshots y movimientos de stock conciliados.
- Otra fuente transaccional aprobada y trazable.

La presencia nunca entra como sustituto de ventas. La ventana temporal, la unidad de salida, el baseline y el control de doble conteo deben formar parte del lineage.

### 4.4 `sales-events`

Son eventos de venta procedentes de una fuente POS/ERP canónica dentro del perímetro integrado y autorizado. Antes de agregar deben comprobarse:

- Fuente y canal canónicos.
- Clave anti-duplicado.
- Variante y unidad.
- Timestamp y zona horaria.
- Correcciones, anulaciones o devoluciones.
- No sumar un evento POS con un movimiento de stock que representa la misma operación.

Una salida externa estándar requiere `N>=10` y permanece agregada. No se extrapola al mercado completo.

### 4.5 Stock

Stock es un snapshot o señal de inventario con tracking activo y fecha de captura. Externamente se publica como rango, índice o bucket agregado.

Reglas de desconocidos:

- `stock=-1` o tracking inactivo: desconocido/no gestionado; nunca cero.
- `stock=0`: agotado solo si el tracking está activo y la fuente lo confirma.
- Valor ausente: ausente; no se imputa automáticamente.

Stock dormido es una señal versionada, no una lectura universal del mercado ni una instrucción automática de liquidación.

### 4.6 `margin-signals` y `required_if_available`

`margin-signals` describe presión de margen, reposición, liquidación o surtido mediante rangos, índices o categorías agregadas. Nunca publica margen, coste o acuerdo comercial exacto por cuenta.

Su contrato es `required_if_available`:

| Estado de fuente | Respuesta obligatoria |
| --- | --- |
| Disponible y autorizada | Valor agregado + `N` + cobertura + periodo + confianza + lineage + caveat |
| No integrada | `value=null`, estado `unavailable`, motivo `source_missing` |
| Sin permiso | `value=null`, estado `unavailable`, motivo `permission_missing` |
| Cobertura insuficiente | Resultado suprimido, motivo `coverage_insufficient` |
| Pipeline no validado | Estado `unavailable`, motivo `pipeline_not_ready` |

`required_if_available` no autoriza estimar, no obliga a la fuente a compartir el dato y nunca convierte ausencia en cero.

### 4.7 `identity_match_confidence`

Score técnico de `0` a `1` que estima si un registro corresponde a la entidad de vino correcta.

| Banda | Uso |
| --- | --- |
| `>=0,85` | Apto para análisis específico, sujeto además a permisos, N, cobertura y privacidad |
| `>=0,70` y `<0,85` | Solo categorías o buckets agregados; no atribuir a una referencia concreta |
| `<0,70` | Excluir de métricas y claims; enviar a revisión/rematching |

Un registro excluido por matching no es una ausencia de mercado. Es un registro no utilizable.

`identity_match_confidence` no es:

- Confianza del claim.
- Cobertura.
- Exactitud garantizada.
- Consentimiento.
- Calidad de la fuente original.

### 4.8 Cobertura

```txt
cobertura = restaurantes con la métrica usable
            / restaurantes cubiertos dentro del scope
```

El denominador debe pertenecer a la misma métrica, scope y periodo.

| Cobertura | Lectura permitida |
| --- | --- |
| `>=70%` alta | Claim direccional fuerte dentro de la muestra cubierta |
| `40-69%` media | Lenguaje prudente: “indica”, “sugiere”, “en la muestra” |
| `20-39%` baja | Señal exploratoria o scoping; no titular comercial fuerte |
| `<20%` o denominador incierto | No publicar claim externo |

Una cobertura alta de un scope sesgado sigue conservando ese sesgo. Cobertura no significa representatividad automática.

### 4.9 `N`

`N` siempre cuenta **restaurantes distintos que contribuyen al bucket publicado** después de permisos, filtros, deduplicación, matching y exclusiones.

`N` no cuenta:

- Filas.
- Cartas.
- Vinos.
- PVP.
- Eventos de venta.
- Snapshots.

Mínimos:

| Insight | Salida externa estándar | Excepción |
| --- | --- | --- |
| Presencia, PVP, share, benchmark y fit | `N>=5` | Ninguna si hay reidentificación o dominancia |
| Ventas, rotación, stock, coste y margen | `N>=10` | `N>=5` solo en piloto cerrado, revisión producto/legal y salida agregada |
| Bucket hipersegmentado | `N>=5` más baja reidentificación | Subir geografía o agrupar categoría |
| CSV externo | `N>=5` por fila | Sin IDs, URL, coordenadas finas ni timestamps identificables |

Si no se alcanza el mínimo: ampliar periodo, subir geografía, agrupar categoría, retirar desglose o responder “sin muestra suficiente”.

### 4.10 Periodo

Periodo incluye inicio, fin, zona horaria, fecha de corte y, cuando aplica, cadencia y última actualización de cada fuente.

| Lectura temporal | Requisito mínimo |
| --- | --- |
| Foto actual | Una fecha de corte válida |
| Señal temprana | 30-60 días, snapshots comparables y cadencia estable |
| Claim trimestral | Al menos 90 días y control de duplicados/frescura |
| Estacionalidad/anual | Al menos 12 meses de histórico estable y revisión metodológica |

Con dos snapshots puede decirse “cambio observado entre fecha A y fecha B”. No debe llamarse tendencia robusta sin histórico suficiente.

### 4.11 Lineage

Lineage es la cadena auditable desde la fuente hasta la salida. Debe conservar internamente:

1. Fuente canónica y tipo de permiso.
2. Snapshot, lote o rango de eventos.
3. Versión de normalización y taxonomía.
4. Versión del matcher y umbral aplicado.
5. Regla de deduplicación y anti-doble conteo.
6. Exclusiones y motivos.
7. Método de agregación y percentil/score.
8. Regla de privacidad y muestra mínima.
9. Versión de metodología.
10. Fecha de generación y canal de salida.

La salida externa muestra una versión segura y comprensible del lineage. Los IDs sensibles permanecen internos.

### 4.12 Confianza del claim

Es un score separado, de `0` a `100`, que resume N, cobertura, frescura, lineage, matching, estabilidad y riesgo de reidentificación.

| Score | Lenguaje |
| --- | --- |
| `>=80` alta | “Observamos”, “el benchmark muestra”, “la muestra soporta” |
| `60-79` media | “Indica”, “sugiere”, “hay evidencia suficiente para priorizar” |
| `40-59` baja | “Señal inicial”, “hipótesis a validar”, “ampliar cobertura” |
| `<40` | No publicar claim; usar solo para scoping interno |

La confianza orienta el lenguaje. No concede permiso, no elimina caveats y no es probabilidad de éxito comercial.

## 5. Registro de claims

El registro canónico, con condiciones y términos relacionados, vive en `data/cellaria_methodology.json`.

### 5.1 Significado de los estados

- **Permitido:** puede salir cuando supera las guardas estándar de fuente, matching, N, cobertura, periodo, privacidad y caveat.
- **Condicionado:** además de las guardas estándar necesita una fuente o permiso especial, revisión adicional o un histórico concreto.
- **Bloqueado:** no se usa en la salida externa estándar. Solo una metodología y aprobación nuevas pueden cambiar su estado.

“Permitido” nunca significa “sin condiciones”.

### 5.2 Claims permitidos

| Claim | Redacción segura | Condiciones mínimas |
| --- | --- | --- |
| Presencia observada | “En la muestra cubierta, la categoría aparece en cartas del scope declarado.” | `N>=5`, cobertura, periodo, matching, caveat de presencia |
| PVP p25/p50/p75 | “El PVP observado se sitúa en esta banda dentro de la muestra.” | `N>=5`, moneda/formato/fiscalidad normalizados, lineage |
| Benchmark agregado | “Comparamos referencias equivalentes con cobertura visible.” | Taxonomía y comparables revisados, N mínimo |
| Fit comercial | “Priorizamos segmentos anónimos con compatibilidad observada.” | Bucket/score, baja reidentificación, validación comercial posterior |

### 5.3 Claims condicionados

| Claim | Condición adicional |
| --- | --- |
| Rotación agregada | Fuente transaccional/stock autorizada, baseline, anti-doble conteo, `N>=10` externo |
| Sell-out agregado | POS/ERP canónico, permiso, `N>=10`, sin detalle por establecimiento |
| Riesgo de stock dormido | Tracking activo, frescura, desconocidos separados de cero, índice/rango |
| Presión de margen | `margin-signals` disponible y autorizada, `required_if_available`, `N>=10` |
| Comparación entre zonas | Cobertura y composición comparables, mismo periodo y taxonomía |
| Cambio entre snapshots | Fechas y composición comparables; no llamarlo tendencia robusta |
| Identidad de establecimiento | Consentimiento/base contractual, tier, finalidad y revisión de reidentificación |
| Hipótesis de ROI | Supuestos y fórmula visibles, etiqueta de estimación, sin garantía |

### 5.4 Claims bloqueados

| No decir | Alternativa segura |
| --- | --- |
| “Este restaurante vende X botellas.” | Sell-out agregado en la cobertura autorizada, si cumple mínimos |
| “Sabemos el margen/coste exacto de cada cuenta.” | Rango o índice agregado de presión de margen |
| “Esta referencia tiene X% de cuota total.” | Presencia/share dentro de la muestra y denominador declarados |
| “Es el número uno del mercado.” | Ranking dentro de una muestra y taxonomía definidas, si es publicable |
| “Venderás X unidades / garantizamos ventas.” | Priorización analítica para validación comercial |
| “El matching es 100% exacto.” | Matching probabilístico con umbrales, exclusiones y revisión |
| “Los datos son en tiempo real.” | Cadencia disponible y fecha de corte visible |
| “El precio causó la rotación.” | Asociación observada o hipótesis pendiente de diseño causal |

También permanecen bloqueados sin metodología específica:

- Cobertura completa del mercado.
- Predicción de ventas.
- Causalidad o elasticidad.
- Tendencia 3m/12m sin histórico suficiente.
- Identidad o contacto sin consentimiento.
- Liderazgo o superioridad no verificable.

## 6. Vista “Explica este número”

Cada número explicable debe exponer este sobre mínimo:

```json
{
  "metric_id": "presence",
  "display_value": "38%",
  "result_status": "publishable",
  "safe_statement": "...",
  "formula": "...",
  "method_label": "...",
  "numerator": { "value": 9, "label": "..." },
  "denominator": { "value": 24, "label": "..." },
  "n": { "value": 24, "minimum": 5, "assessment": "cumple" },
  "coverage": { "value": 0.75, "usable": 24, "scope_total": 32 },
  "period": { "start": "...", "end": "...", "cutoff": "..." },
  "scope": ["..."],
  "matching": { "rule": "...", "excluded_records": 2 },
  "claim_confidence": { "value": 82, "label": "Alta" },
  "lineage": ["..."],
  "checks": ["..."],
  "does_not_mean": ["..."],
  "caveat": "..."
}
```

Estados de resultado:

- `publishable`: supera las guardas; se muestra con caveat.
- `conditioned`: puede mostrarse solo con lenguaje y canal restringidos.
- `unavailable`: la fuente o el permiso no existen; el valor permanece nulo.
- `blocked`: existe un cálculo interno, pero N, cobertura, privacidad, confianza o registro impiden publicarlo.

La vista no debe presentar `N`, cobertura o confianza como parte de una falsa ecuación. Son guardas y metadatos del resultado, no necesariamente operandos de la métrica.

## 7. Checklist de publicación

- [ ] Scope, métrica, decisión y canal definidos.
- [ ] Fuente y permiso revisados.
- [ ] Presencia, ventas, stock, coste y margen permanecen separados.
- [ ] Matching aplica `>=0,85`, `>=0,70 y <0,85`, `<0,70` sin solapamientos.
- [ ] `N` cuenta restaurantes distintos.
- [ ] El mínimo aplicable se cumple en cada bucket.
- [ ] No hay dominancia ni riesgo razonable de reidentificación.
- [ ] Cobertura muestra numerador y denominador.
- [ ] Periodo, fecha de corte y frescura son visibles.
- [ ] Confianza del claim y lenguaje son coherentes.
- [ ] Lineage y versiones están guardados.
- [ ] `required_if_available` no convierte ausencias en cero.
- [ ] Caveat específico junto al claim.
- [ ] Tendencias cumplen el histórico mínimo.
- [ ] Exportaciones no incluyen IDs, URL, coordenadas o timestamps identificables.
- [ ] Prensa, publicidad, partners, identidad o comparaciones fuertes están escalados.

## 8. Mensaje de producto

Frase segura:

> Cellaria transforma señales agregadas de cartas, PVP y, cuando hay permiso y fuente suficiente, ventas, stock, rotación y margen en una lectura comercial con muestra, cobertura, confianza y límites visibles.

Disclaimer general:

> Datos basados en fuentes analizadas por Cellaria. La cobertura puede ser parcial y los resultados deben interpretarse como señales agregadas, no como ventas reales ni representación total del mercado.

## 9. Archivos de implementación

- UI: `methodology.html`
- Interacción: `cellaria-methodology.js`
- Estilos: `cellaria-methodology.css`
- Contrato de contenido: `data/cellaria_methodology.json`
- Documento normativo: `CELLARIA_METHODOLOGY_AND_CLAIMS_2026-07-14.md`