# zcatsql

> SQLite wrapper idiomático para Zig 0.15.2+

Parte del ecosistema **zcat**: `zcatui` (TUI), `zcatgui` (GUI), `zcatsql` (SQLite)

## Estado

**v1.1** | ~12,000 líneas | 16 módulos | 80 tests

## Quick Start

```bash
zig build              # Compilar
zig build test         # Tests (80/80)
./zig-out/bin/basic    # Ejemplo
```

## Arquitectura

```
src/
├── root.zig        # Exports públicos
├── database.zig    # Conexión, transacciones, pragmas, snapshots
├── statement.zig   # Prepared statements, binding, row mapping
├── session.zig     # Change tracking (Session extension)
├── serialize.zig   # Serialize/Deserialize API
├── functions.zig   # UDFs, callbacks, hooks
├── backup.zig      # Backup API, Blob I/O
├── pool.zig        # Connection pool
├── fts5.zig        # Full-text search
├── json.zig        # JSON1 helpers
├── rtree.zig       # R-Tree spatial index
├── vtable.zig      # Virtual tables API
├── types.zig       # Tipos comunes
├── errors.zig      # Mapeo de errores
├── c.zig           # C bindings
└── audit/          # Sistema de auditoría
    ├── mod.zig     # Exports
    ├── log.zig     # AuditLog principal
    ├── entry.zig   # Entry + JSON
    ├── context.zig # User/app context
    ├── index.zig   # File index
    ├── writer.zig  # File rotation
    └── verify.zig  # Hash chain verification
```

## Documentación

| Archivo | Contenido |
|---------|-----------|
| `REFERENCE.md` | **Manual técnico completo** (1566 líneas) - API, ejemplos, tipos |
| `docs/AUDIT_LOG_DESIGN.md` | Diseño del sistema de auditoría |
| `docs/API.md` | Referencia API detallada |
| `docs/ARCHITECTURE.md` | Arquitectura del proyecto |
| `README.md` | Introducción y ejemplos básicos |
| `examples/basic.zig` | Ejemplo ejecutable completo |

## SQLite Flags

```
-DSQLITE_THREADSAFE=2          # Multi-thread (required for ConnectionPool)
-DSQLITE_ENABLE_FTS5            # Full-text search
-DSQLITE_ENABLE_JSON1           # JSON functions
-DSQLITE_ENABLE_RTREE           # R-Tree spatial
-DSQLITE_ENABLE_SESSION         # Change tracking
-DSQLITE_ENABLE_SNAPSHOT        # Snapshots
-DSQLITE_ENABLE_COLUMN_METADATA
-DSQLITE_ENABLE_PREUPDATE_HOOK  # Pre-update hooks (audit)
```

## Notas Zig 0.15

| Cambio | Solución |
|--------|----------|
| `ArrayList.init` no existe | Usar `ArrayListUnmanaged` + `.empty` |
| `callconv(.C)` | Cambiar a `callconv(.c)` (minúscula) |
| `bufferedReader()` | Usar `readFileAlloc` |
| Strings para SQLite | `allocPrint` + null terminator |
| Named params | Incluir prefijo (`:name`) |

## Audit Log

```zig
var audit = try AuditLog.init(allocator, &db, .{
    .log_dir = "/var/log/audit",
    .app_name = "my_app",
});
defer audit.deinit();
audit.start();  // IMPORTANTE: después de que struct esté en memoria final
```

**Verificar integridad:**
```zig
var result = try verifyAuditChain(allocator, "/var/log/audit");
defer result.deinit(allocator);
if (!result.valid) { /* ALERTA */ }
```

---

## TEAM STANDARDS

**Ubicación:** `/mnt/cello2/arno/re/recode/teamdocs/`

### Normas Esenciales

**NUNCA:**
- Ejecutar binarios en background (`&`) - shells zombies
- Commit sin testing
- Silenciar warnings
- Duplicar código (verificar common/ primero)
- Archivos >600 líneas
- Modificar scope sin consultar

**SIEMPRE:**
- DRY - Una función por tarea
- Testing progresivo (compilar + verificar)
- Security commits antes de refactorizaciones
- Actualizar CLAUDE.md cada sesión
- Fragmentar: <400 líneas (core), <200 (utils)

### Comunicación
- Directo al grano, sin preámbulos
- Honestidad técnica total
- Si algo está mal, decirlo y explicar

### Workflow
1. Leer `teamdocs/LAST_UPDATE.md`
2. Leer CLAUDE.md del proyecto
3. Implementar con testing progresivo
4. Actualizar documentación
5. Commit tras confirmación usuario

### Documentos Clave
- `QUICK_REFERENCE.md` - Cheat sheet (<1 min)
- `NORMAS_TRABAJO_CONSENSUADAS.md` - Metodología completa
- `NORMAS_PATRONES_DESARROLLO.md` - Patrones específicos

---

## Git

```
origin: git@git.reugenio.com:reugenio/zcatsql.git
branch: main
```

## Zig Path

```bash
ZIG=/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2/zig
```