system-docs/v4-archive/hst/docs/spec/HST_SPEC_v1.md

# HST - Especificación Técnica
**Sistema de Etiquetado Semántico basado en Hashes**

**Versión:** 1.0  
**Fecha:** 2025-12-10  
**Estado:** Borrador para implementación

---

# 1. Visión General

## 1.1 Propósito

HST (Hash Semantic Tagging) es un sistema de etiquetado universal que:
- Representa conceptos mediante imágenes e identificadores criptográficos
- Desvincula el significado del lenguaje humano
- Permite múltiples estilos visuales sin alterar la semántica
- Soporta bibliotecas de sistema y de usuario
- Está diseñado para uso en documentos, presentaciones y aplicaciones profesionales

## 1.2 Principios fundamentales

1. **Identidad inmutable**: El hash SHA-256 de la imagen primigenia es la referencia absoluta
2. **Separación semántica/visual**: Los estilos no alteran el significado
3. **Códigos memorizables**: Agilidad de uso mediante códigos cortos
4. **Jerarquía flexible**: Múltiples árboles y relaciones entre etiquetas
5. **Extensibilidad**: Usuarios pueden crear etiquetas propias

---

# 2. Imagen Primigenia

## 2.1 Definición

La imagen primigenia es el archivo visual origen de cada etiqueta.

## 2.2 Requisitos

- Formato: PNG (por defecto), extensible a otros formatos
- Sin metadatos: EXIF, ICC, XMP eliminados
- Archivo limpio y 100% reproducible
- Cualquier cambio genera un concepto diferente

## 2.3 Proceso de limpieza

```
1. Recibir imagen original
2. Eliminar todos los metadatos (EXIF, ICC, XMP)
3. Normalizar canal Alpha si existe
4. Resultado: Buffer binario puro
```

---

# 3. Hash Maestro (H_maestro)

## 3.1 Generación

```
H_maestro = SHA256(imagen_primigenia_limpia)
```

## 3.2 Propiedades

- Longitud: 64 caracteres hexadecimales
- Inmutable: nunca cambia para una imagen dada
- Único: identifica el concepto de forma absoluta
- Independiente del nombre, idioma o estilo visual

## 3.3 Ejemplo

```
Imagen: factura.png (limpia)
H_maestro: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2
```

---

# 4. Sistema de Estilos (Skins)

## 4.1 Propósito

Permitir múltiples variantes visuales de un concepto sin alterar su identidad.

## 4.2 Capacidad

- 4 caracteres hexadecimales = 65,536 estilos posibles (0000-FFFF)
- Estilo `0000` reservado implícitamente (no se usa, la primigenia no lleva estilo)

## 4.3 Algoritmo de hash visible

```
Entrada:
  H_maestro (64 chars): a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2
  estilo (4 chars): 0A3F

Proceso:
  1. Tomar primeros 60 caracteres de H_maestro
  2. Dividir en dos mitades de 30 caracteres
     - H_left = chars 0-29
     - H_right = chars 30-59
  3. Descartar últimos 4 caracteres (60-63)
  4. Insertar estilo entre las dos mitades

Resultado:
  hash_visible = H_left + estilo + H_right
  hash_visible = a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5 + 0A3F + p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0
```

## 4.4 Almacenamiento

| Tipo | Hash | Ruta |
|------|------|------|
| Primigenia | H_maestro completo (64 chars) | `/hst/primigenias/{H_maestro}.png` |
| Skin | hash_visible (64 chars) | `/hst/skins/{hash_visible}.png` |

## 4.5 Comportamiento

- La imagen primigenia se almacena con H_maestro original (sin modificar)
- Cada skin se almacena con su hash_visible calculado
- En base de datos siempre se guarda H_maestro como referencia

---

# 5. Grupos y Extensiones

## 5.1 Definición de grupos

| Grupo | Propiedad | Memorizable | Formato código | Descripción |
|-------|-----------|-------------|----------------|-------------|
| `hst` | Sistema | ✅ Sí | Alfabético único | Etiquetas semánticas base |
| `spe` | Sistema | ❌ No | "spe" repetido | Especificaciones técnicas |
| `hsu` | Usuario | ❌ No | "hsu" repetido | Etiquetas de usuario |
| `msu` | Usuario | ✅ Sí | Ordinal (001-999) | Proyectos de usuario |

## 5.2 Filosofía de códigos

**Códigos memorizables (hst, msu):**
- Objetivo: agilizar uso mediante memorización
- Ejemplos: `inv` (factura), `dnt` (albarán), `105` (proyecto)

**Códigos repetidos (spe, hsu):**
- Objetivo: indicar categoría, no identificar
- El hash es la referencia real
- Compromiso entre utilidad y limpieza de biblioteca

## 5.3 Ejemplos

```
Etiqueta sistema memorizable:
  grupo: "hst"
  codigo: "inv"
  nombre_es: "factura"
  nombre_en: "invoice"

Especificación sistema:
  grupo: "spe"
  codigo: "spe"
  nombre_es: "dc 24v"
  nombre_en: "dc 24v"

Etiqueta usuario:
  grupo: "hsu"
  codigo: "hsu"
  nombre_es: "mi concepto"

Proyecto usuario:
  grupo: "msu"
  codigo: "105"
  nombre_es: "SAGRADA FAMILIA 25"
```

---

# 6. Cadena de Metadatos

## 6.1 Estructura

```
cadena_metadatos: [
  H_maestro_raiz,
  H_maestro_nivel1,
  H_maestro_nivel2,
  ...,
  H_maestro_actual,
  H_propiedad,
  H_acceso
]
```

## 6.2 Componentes

| Posición | Campo | Descripción |
|----------|-------|-------------|
| 0..n-3 | Jerarquía | Hashes de ancestros hasta raíz |
| n-2 | H_maestro | Hash de la etiqueta actual |
| n-1 | H_propiedad | Propietario (ver sección 7) |
| n | H_acceso | Llave de acceso (ver sección 8) |

## 6.3 Cadena de códigos (auxiliar)

Para legibilidad humana, se mantiene cadena de códigos separada por guiones:

```
jerarquia_codigos: "mhs-flg-rul-spc-spe"
```

---

# 7. H_propiedad

## 7.1 Definición

Identifica el propietario/origen de la etiqueta.

## 7.2 Valores según grupo

| Grupo | H_propiedad |
|-------|-------------|
| `hst` | Hash de la etiqueta "hst" del sistema |
| `spe` | Hash de la etiqueta "especificación" del sistema |
| `hsu` | Hash del identificador de usuario creador |
| `msu` | Hash del identificador de usuario creador |

## 7.3 Nota

La implementación exacta se definirá con el sistema de usuarios y monetización.

---

# 8. H_acceso

## 8.1 Definición

Llave de acceso que controla quién puede descargar/usar la imagen.

## 8.2 Estado

**PENDIENTE DEFINIR**

Relacionado con:
- Sistema de monetización futuro
- Compartición de bibliotecas entre usuarios
- Colaboración en proyectos (msu)

## 8.3 Notas para implementación futura

- Inicialmente la cadena completa estará en NocoDB
- Se exploró embeber en metadatos PNG (pendiente validar viabilidad)
- Los grupos hsu/msu permiten compartición (mecanismo por definir)
- Diferenciación de grupos define reglas de acceso diferentes

---

# 9. Schema de Base de Datos

## 9.1 Tabla: hst_tags

Almacena todas las etiquetas del sistema.

| Campo | Tipo | Restricciones | Descripción |
|-------|------|---------------|-------------|
| id | UUID | PK | Identificador interno |
| h_maestro | CHAR(64) | UNIQUE, NOT NULL | Hash SHA-256 de imagen primigenia |
| grupo | ENUM | NOT NULL | hst, spe, hsu, msu |
| codigo | VARCHAR(10) | NOT NULL | Código memorizable o repetido |
| nombre_es | VARCHAR(255) | NOT NULL | Nombre en español |
| nombre_en | VARCHAR(255) | | Nombre en inglés |
| imagen_url | VARCHAR(500) | | URL temporal (migración) |
| h_propiedad | CHAR(64) | | Hash de propietario |
| h_acceso | CHAR(64) | | Llave de acceso |
| created_at | TIMESTAMP | DEFAULT NOW() | Fecha creación |
| metadata | JSONB | | Datos extensibles |

## 9.2 Tabla: hst_trees

Define árboles jerárquicos. Una etiqueta puede aparecer en múltiples árboles.

| Campo | Tipo | Restricciones | Descripción |
|-------|------|---------------|-------------|
| id | UUID | PK | Identificador interno |
| tree_name | VARCHAR(100) | NOT NULL | Nombre del árbol |
| h_maestro | CHAR(64) | FK → hst_tags | Etiqueta |
| h_padre | CHAR(64) | FK → hst_tags, NULL | Padre (null = raíz) |
| orden | INT | | Posición entre hermanos |
| rango | INT | | Profundidad en árbol |

## 9.3 Tabla: hst_relations

Grafo de relaciones entre etiquetas. Direccional con peso.

| Campo | Tipo | Restricciones | Descripción |
|-------|------|---------------|-------------|
| id | UUID | PK | Identificador interno |
| h_from | CHAR(64) | FK → hst_tags | Etiqueta origen |
| h_to | CHAR(64) | FK → hst_tags | Etiqueta destino |
| peso | DECIMAL | | Fuerza de relación (0-1) |
| tipo | VARCHAR(50) | | related, part_of, type_of... |
| metadata | JSONB | | Datos extensibles |

## 9.4 Tabla: hst_skins

Estilos disponibles por etiqueta.

| Campo | Tipo | Restricciones | Descripción |
|-------|------|---------------|-------------|
| id | UUID | PK | Identificador interno |
| h_maestro | CHAR(64) | FK → hst_tags | Etiqueta base |
| estilo | CHAR(4) | NOT NULL | Código de estilo (0000-FFFF) |
| hash_visible | CHAR(64) | UNIQUE | Hash calculado con estilo |
| nombre | VARCHAR(50) | | Nombre del estilo |
| tipo | VARCHAR(20) | | basic, premium, custom |

---

# 10. Estructura de Archivos

## 10.1 Directorios

```
/hst/
├── primigenias/
│   └── {H_maestro}.png
└── skins/
    └── {hash_visible}.png
```

## 10.2 Reglas

- Primigenias: siempre con H_maestro original completo
- Skins: siempre con hash_visible calculado
- Formato PNG por defecto
- Sin metadatos embebidos (inicialmente)

---

# 11. Pipeline de Importación

## 11.1 Desde Airtable (migración inicial)

```
1. Leer registro de Airtable
2. Descargar imagen desde URL
3. Limpiar metadatos (EXIF, ICC, XMP)
4. Calcular SHA-256 → H_maestro
5. Determinar grupo (hst, spe, hsu, msu)
6. Renombrar archivo → {H_maestro}.png
7. Subir a /hst/primigenias/
8. Crear registro en NocoDB (hst_tags)
9. Crear entradas en hst_trees según jerarquía
10. Actualizar referencias
```

## 11.2 Nueva etiqueta (flujo normal)

```
1. Usuario sube imagen
2. Sistema limpia metadatos
3. Calcula H_maestro
4. Verifica unicidad (no duplicados)
5. Asigna grupo y código
6. Almacena primigenia
7. Crea registro en base de datos
8. Genera skins si aplica
```

---

# 12. Integraciones

## 12.1 n8n (Alfred)

- Pipeline de importación automatizado
- Asignación de etiquetas en flujos OCR
- Sincronización con Airtable (migración)

## 12.2 API REST

```
GET  /api/v1/tags                     # Listar etiquetas
GET  /api/v1/tags/{h_maestro}         # Obtener etiqueta
GET  /api/v1/tags/{h_maestro}/image   # Obtener imagen primigenia
GET  /api/v1/tags/{h_maestro}/skins   # Listar skins
POST /api/v1/tags                     # Crear etiqueta
GET  /api/v1/search?q=...             # Buscar
GET  /api/v1/trees/{tree_name}        # Obtener árbol
GET  /api/v1/relations/{h_maestro}    # Obtener relaciones
```

## 12.3 Futuro: App Cliente

- Drag & drop universal
- Sincronización de bibliotecas
- Creación de etiquetas usuario

---

# 13. Consideraciones de Seguridad

## 13.1 Integridad

- H_maestro garantiza integridad de imagen
- Cualquier alteración genera hash diferente
- Verificación posible en cualquier momento

## 13.2 Acceso

- H_acceso controlará permisos (pendiente definir)
- Grupos definen reglas base de visibilidad
- Sistema vs usuario claramente separados

## 13.3 Almacenamiento

- Rutas públicas pero no indexadas
- Migración futura a almacenamiento descentralizado (Filecoin/IPFS)

---

# 14. Glosario

| Término | Definición |
|---------|------------|
| H_maestro | Hash SHA-256 de imagen primigenia (64 chars) |
| hash_visible | Hash con estilo insertado (64 chars) |
| Imagen primigenia | Archivo imagen sin metadatos, origen del concepto |
| Skin | Variante visual de una etiqueta |
| Grupo | Categoría de etiqueta (hst, spe, hsu, msu) |
| Código | Identificador corto memorizable |
| Cadena de metadatos | Array de hashes: jerarquía + propiedad + acceso |

---

# 15. Pendientes y TODOs

## Definición
- [ ] Mecanismo de compartición de bibliotecas usuario
- [ ] Modelo de monetización y relación con H_acceso
- [ ] Validar viabilidad de metadatos embebidos en PNG
- [ ] Permisos de colaboración en proyectos (msu)
- [ ] Definir estilos iniciales a implementar

## Implementación
- [ ] Pipeline de limpieza de metadatos
- [ ] Cálculo de H_maestro para etiquetas existentes
- [ ] Migración desde Airtable
- [ ] API REST
- [ ] Integración n8n

---

# 16. Historial de Cambios

| Versión | Fecha | Cambios |
|---------|-------|---------|
| 1.0 | 2025-12-10 | Versión inicial |

---

**Fin del documento**