@designerbyron/lifecode-rag 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +220 -2
  3. package/bin/lifecode-rag.mjs +449 -0
  4. package/client.js +3515 -0
  5. package/cordis.patch.yml +3 -0
  6. package/docs/ARCHITECTURE-v0.2.md +269 -0
  7. package/docs/AUTO-DISCOVERY.md +111 -0
  8. package/docs/AUTOMATION-POLICIES.md +232 -0
  9. package/docs/CONTRATO-v0.1.md +195 -0
  10. package/docs/EMBEDDING-PROVIDERS.md +105 -0
  11. package/docs/OBSERVABILITY.md +241 -0
  12. package/docs/PA-UI-0-API-CONTRACT.md +887 -0
  13. package/docs/PERFORMANCE-BUDGETS.md +118 -0
  14. package/docs/PROJECT-AWARE-ARCHITECTURE.md +580 -0
  15. package/docs/PROJECT-AWARE-DATA-CONTRACT.md +411 -0
  16. package/docs/PROJECT-AWARE-ERROR-CONTRACT.md +112 -0
  17. package/docs/PROJECT-AWARE-SESSION-CONTRACT.md +120 -0
  18. package/docs/WORKSPACE-API.md +239 -0
  19. package/icon.svg +7 -0
  20. package/index.js +198 -0
  21. package/lib/audit-export.mjs +70 -0
  22. package/lib/audit.mjs +120 -0
  23. package/lib/auto-context.mjs +322 -0
  24. package/lib/automation.mjs +214 -0
  25. package/lib/chunk.mjs +100 -0
  26. package/lib/config-resolve.mjs +119 -0
  27. package/lib/context.mjs +150 -0
  28. package/lib/conversation-events.mjs +145 -0
  29. package/lib/db.mjs +309 -0
  30. package/lib/diagnose.mjs +197 -0
  31. package/lib/discovery.mjs +402 -0
  32. package/lib/doctor.mjs +82 -0
  33. package/lib/embed.mjs +96 -0
  34. package/lib/embedders.mjs +103 -0
  35. package/lib/errors.mjs +231 -0
  36. package/lib/exec-context.mjs +238 -0
  37. package/lib/extract.mjs +260 -0
  38. package/lib/harness-workspaces.mjs +85 -0
  39. package/lib/hash.mjs +34 -0
  40. package/lib/ingest.mjs +239 -0
  41. package/lib/inputs.mjs +67 -0
  42. package/lib/library-state.mjs +252 -0
  43. package/lib/maintenance.mjs +113 -0
  44. package/lib/metrics.mjs +164 -0
  45. package/lib/migrate.mjs +373 -0
  46. package/lib/operations.mjs +132 -0
  47. package/lib/pa-api.mjs +946 -0
  48. package/lib/paths.mjs +345 -0
  49. package/lib/policy.mjs +125 -0
  50. package/lib/profile.mjs +128 -0
  51. package/lib/readmodel.mjs +159 -0
  52. package/lib/recovery.mjs +557 -0
  53. package/lib/registry-schema.mjs +206 -0
  54. package/lib/registry.mjs +606 -0
  55. package/lib/resolve.mjs +318 -0
  56. package/lib/retention.mjs +143 -0
  57. package/lib/revocation.mjs +124 -0
  58. package/lib/roots-structure.mjs +224 -0
  59. package/lib/schema.mjs +173 -0
  60. package/lib/scope-ops.mjs +379 -0
  61. package/lib/scope-stores.mjs +128 -0
  62. package/lib/search.mjs +345 -0
  63. package/lib/selection.mjs +225 -0
  64. package/lib/server.mjs +340 -0
  65. package/lib/session-identity.mjs +51 -0
  66. package/lib/sessions.mjs +343 -0
  67. package/lib/sync-scheduler.mjs +354 -0
  68. package/lib/sync.mjs +755 -0
  69. package/lib/tags.mjs +45 -0
  70. package/lib/tools.mjs +364 -0
  71. package/lib/trusted-roots.mjs +149 -0
  72. package/lib/worker-context.mjs +22 -0
  73. package/package.json +67 -5
@@ -0,0 +1,195 @@
1
+ # Contrato de herramientas — LifeCode RAG v0.1.0
2
+
3
+ **Estado:** CONGELADO el 2026-11-17. Este documento fija la superficie pública de la versión 0.1.0:
4
+ siete herramientas `lifecode_rag_*`, sus entradas, salidas, permisos, límites y errores. Cambiar
5
+ cualquiera de esos puntos exige una versión nueva y su propia matriz de aceptación; no se amplía el
6
+ alcance por acumulación.
7
+
8
+ Base verificable: `node --test` (66/66), `node tools/check.mjs` (estructura, cero dependencias, cero
9
+ red) y `node tools/hermetic.mjs` (la suite no toca el almacén real). La matriz de aceptación
10
+ AC1–AC29 y sus estados viven en [`ACEPTACION-v0.1.md`](ACEPTACION-v0.1.md).
11
+
12
+ ## Reglas comunes
13
+
14
+ - **Sólo herramientas, sin UI y sin sección de system prompt.** La superficie pública son las siete
15
+ herramientas; el plugin no registra paneles, rutas web ni texto de sistema.
16
+ - **Cero dependencias.** `package.json` no declara dependencias, peerDependencies ni optionalDependencies,
17
+ y ningún fuente importa `@deepseek-ai/*`.
18
+ - **Cero red.** Ningún módulo usa `fetch`, `node:http(s)`, `node:net` ni `node:dns`; el comprobador
19
+ `tools/check.mjs` lo verifica y falla si aparece.
20
+ - **Almacén propio.** SQLite en `$DSH_HOME/lifecode-rag/rag.sqlite3` (o `LIFECODE_RAG_ROOT`); nunca
21
+ lee ni escribe el almacén del Skill Center.
22
+ - **Fallo en cerrado.** Una aprobación denegada, ausente o no disponible, una ruta protegida, un
23
+ enlace duro, un enlace simbólico o un índice inconsistente producen error; nunca una escritura
24
+ parcial ni una respuesta "vacía pero correcta".
25
+ - **Resultado de herramienta.** El valor devuelto es un objeto JSON serializable; el adaptador lo
26
+ renderiza como un bloque de texto legible con la misma información. Un fallo llega como
27
+ `{ isError: true, error: { message, info? } }` y el mensaje empieza por el código estable
28
+ (`path-denied: …`), para que el modelo y las pruebas puedan distinguir la causa.
29
+
30
+ ### Códigos de error estables
31
+
32
+ Fuente única de verdad: `RAG_CODES` en `lib/errors.mjs` declara **25** códigos. De ellos, **20** se emiten
33
+ hoy, **5** están reservados (declarados y sin emisión) y **3** se emiten sin estar declarados: una deuda
34
+ interna registrada, no un cambio de contrato. En total, el código emite **23** códigos distintos.
35
+
36
+ **Emitidos (23)**
37
+
38
+ `invalid-argument`, `invalid-config`, `invalid-tag`, `store-not-initialized`, `store-not-rag`,
39
+ `store-version-unsupported`, `store-corrupt`, `fts-integrity`, `source-not-found`, `source-unreadable`,
40
+ `path-denied`, `path-not-allowed`, `path-unsupported`, `path-escape`, `hardlink-refused`, `too-large`,
41
+ `too-many-files`, `binary-file`, `approval-required`, `approval-unavailable`, `vector-index-incomplete`,
42
+ `cancelled`, `internal`.
43
+
44
+ **Reservados, sin emisión (5)**
45
+
46
+ `store-busy` (el almacén espera con `busy_timeout` en vez de fallar), `path-outside-root` y
47
+ `path-protected` (sustituidos en la práctica por `path-not-allowed` y `path-denied`),
48
+ `egress-denied` y `embedding-failed` (no hay proveedor remoto en v0.1.0).
49
+
50
+ **Deuda registrada:** `path-escape`, `hardlink-refused` y `vector-index-incomplete` se lanzan desde
51
+ `lib/policy.mjs` y `lib/maintenance.mjs` pero no figuran en `RAG_CODES`. El contrato los documenta porque
52
+ el código los emite; alinearlos en la constante exige tocar código y queda para la siguiente versión
53
+ (no se hace en una reconciliación documental).
54
+
55
+ `codigo: detalle` es el formato del mensaje; los detalles no son contrato y pueden precisarse.
56
+
57
+ ### Límites por defecto
58
+
59
+ | Límite | Valor | Dónde se cambia |
60
+ |---|---|---|
61
+ | Tamaño máximo por fichero | 2 000 000 bytes | `config.json` → `maxFileBytes` |
62
+ | Ficheros por llamada de ingesta | 200 | `maxFilesPerIngest` |
63
+ | Chunk objetivo / máximo / solape | 1200 / 2000 / 120 caracteres | `chunk.*` |
64
+ | Resultados de búsqueda | 8 (máximo 50) | `search.limit`, `search.maxLimit` |
65
+ | Presupuesto de contexto | 2000 tokens estimados | `context.budgetTokens` |
66
+ | Chunks por contexto | 12 | `context.maxChunks` |
67
+ | Diversidad MMR | 0.7 | `context.mmrLambda` |
68
+ | Embedder local | `local-hash-v1`, 256 dimensiones | `embedding.provider`, `embedding.dim` |
69
+
70
+ Los tokens son una **estimación** (`ceil(caracteres / 4)`), no un conteo del tokenizador del modelo;
71
+ la matriz lo declara como límite conocido (AC20, PARTIAL).
72
+
73
+ ## Herramientas
74
+
75
+ ### `lifecode_rag_ingest`
76
+
77
+ Indexa ficheros o directorios de texto del proyecto. Acepta rutas relativas al directorio de la
78
+ sesión o absolutas.
79
+
80
+ | Parámetro | Tipo | Obligatorio | Significado |
81
+ |---|---|---|---|
82
+ | `paths` | string \| string[] | sí | Ficheros o directorios a indexar |
83
+ | `collection` | string | no | Agrupa fuentes para filtrar después |
84
+ | `tags` | string[] | no | Etiquetas normalizadas (máx. 20) |
85
+ | `force` | boolean | no | Reindexa aunque el contenido no haya cambiado |
86
+
87
+ - Recorre directorios omitiendo `.git`, `node_modules`, `.dsh`, `dist`, `build`, `coverage`, enlaces
88
+ simbólicos y junctions.
89
+ - Clasifica **todas** las rutas antes de abrir el almacén: si una sola está protegida, la llamada
90
+ entera falla sin escribir nada.
91
+ - Fuera del proyecto (y de las raíces permitidas) exige aprobación humana con la lista exacta.
92
+ - Formatos: `md`, `txt`, `html`, `json`, `jsonl`, `csv`, `tsv`, `yaml`, `xml`, `logs` y código.
93
+ - Devuelve `{ ingested, skipped, errors, approvedOutside }`; `skipped` son fuentes cuyo contenido no
94
+ cambió (mismo `sha256` y sin `force`), no un fallo.
95
+ - Reingerir el mismo contenido con etiquetas distintas actualiza sólo las etiquetas y **no** sube
96
+ `index_revision` (auditoría `ingest.tags`).
97
+
98
+ ### `lifecode_rag_search`
99
+
100
+ Búsqueda híbrida: FTS5 léxica + similitud de vectores, fusionadas con Reciprocal Rank Fusion (k=60).
101
+ Devuelve fragmentos compactos; el texto completo se pide con `lifecode_rag_get`.
102
+
103
+ | Parámetro | Tipo | Obligatorio | Significado |
104
+ |---|---|---|---|
105
+ | `query` | string | sí | Consulta en lenguaje natural |
106
+ | `limit` | number | no | Resultados (1–50; por defecto 8) |
107
+ | `collection` | string | no | Filtra por colección |
108
+ | `tags` | string[] | no | Filtra por etiquetas |
109
+ | `tagMode` | `any` \| `all` | no | Cualquiera (por defecto) o todas |
110
+
111
+ - Devuelve `{ results, mode, elapsedMs }` con `results[] = { chunkKey, sourceId, uri, title, heading,
112
+ ordinal, rrf, snippet }`. `mode` indica `hybrid` o `fts`.
113
+ - Nunca devuelve el texto completo del chunk: sólo un `snippet` de hasta 240 caracteres.
114
+ - La recuperación es léxica de base; `local-hash-v1` **no** es un modelo semántico y el contrato no
115
+ promete paráfrasis. La medición está en [`BENCHMARK-2026-11-17.md`](BENCHMARK-2026-11-17.md).
116
+
117
+ ### `lifecode_rag_context`
118
+
119
+ Ensambla contexto listo para el modelo con diversificación MMR y citas numeradas verificables.
120
+
121
+ | Parámetro | Tipo | Obligatorio | Significado |
122
+ |---|---|---|---|
123
+ | `query` | string | sí | Consulta |
124
+ | `budgetTokens` | number | no | Presupuesto estimado (por defecto 2000) |
125
+ | `maxChunks` | number | no | Fragmentos máximos (por defecto 12) |
126
+ | `collection` | string | no | Filtra por colección |
127
+ | `tags` | string[] | no | Filtra por etiquetas |
128
+
129
+ - Devuelve `{ text, citations, tokens, truncated, considered }`.
130
+ - `citations[] = { n, chunkKey, sourceId, uri, title, heading, ordinal, charStart, charEnd }`.
131
+ - Si el primer fragmento no cabe en el presupuesto, devuelve `text` vacío y `truncated: true`; no
132
+ corta un chunk a la mitad ni presenta un contexto incompleto como completo.
133
+
134
+ ### `lifecode_rag_get`
135
+
136
+ Lee una fuente indexada y sus fragmentos completos, para verificar una cita.
137
+
138
+ | Parámetro | Tipo | Obligatorio | Significado |
139
+ |---|---|---|---|
140
+ | `ref` | string | sí | `sourceId` (`src_…`) o URI indexada |
141
+ | `limit` | number | no | Fragmentos a devolver |
142
+
143
+ Devuelve la fuente normalizada (título, uri, colección, etiquetas, hash, fechas, `index_revision`) y
144
+ sus chunks en orden. `source-not-found` si la referencia no existe.
145
+
146
+ ### `lifecode_rag_list`
147
+
148
+ Lista fuentes con filtros y paginación.
149
+
150
+ | Parámetro | Tipo | Obligatorio | Significado |
151
+ |---|---|---|---|
152
+ | `collection` | string | no | Filtra por colección |
153
+ | `tag` | string | no | Filtra por etiqueta |
154
+ | `limit` | number | no | Tamaño de página |
155
+ | `offset` | number | no | Desplazamiento |
156
+
157
+ Devuelve `{ total, rows }` con una fila por fuente y su número de chunks.
158
+
159
+ ### `lifecode_rag_forget`
160
+
161
+ Elimina una fuente y todo lo indexado de ella (chunks, vectores, etiquetas, FTS por cascada).
162
+
163
+ | Parámetro | Tipo | Obligatorio | Significado |
164
+ |---|---|---|---|
165
+ | `ref` | string | sí | `sourceId` o URI |
166
+
167
+ - **Siempre** exige aprobación humana; el motivo incluye el `sourceId` y la URI exactos.
168
+ - Si la aprobación falta, se deniega o no hay respondiente: `approval-required` /
169
+ `approval-unavailable`, sin borrar nada.
170
+ - Devuelve `{ forgotten: true, sourceId, uri }`.
171
+
172
+ ### `lifecode_rag_reindex`
173
+
174
+ Reconstruye el índice de texto, los vectores o ambos.
175
+
176
+ | Parámetro | Tipo | Obligatorio | Significado |
177
+ |---|---|---|---|
178
+ | `operation` | `fts` \| `vectors` \| `all` | sí | Qué reconstruir |
179
+
180
+ - **Siempre** exige aprobación humana. `all` ejecuta primero FTS y después vectores.
181
+ - `fts` es una transacción global: `rebuild`, verificación de integridad, subida de
182
+ `index_revision` y asiento de auditoría, todo o nada.
183
+ - `vectors` va por fuente, con transacción propia, y comprueba entre fuentes si la operación fue
184
+ cancelada (`cancelled`). Al terminar exige que cada chunk tenga su vector
185
+ (`vector-index-incomplete` si falta alguno).
186
+ - Devuelve `{ operation, rebuiltChunks?, rebuiltSources? }`.
187
+
188
+ ## Fuera del contrato v0.1.0
189
+
190
+ No forman parte de esta versión y no deben anunciarse como disponibles: ingesta de PDF/DOCX,
191
+ embeddings neuronales, egress remoto, UI/panel, sección de system prompt, búsqueda por `minScore`,
192
+ formato de contexto alternativo, `list` por tipo de fuente, `forget` por lote, historial de
193
+ versiones de un documento y exportación/importación del almacén. La tabla de desviaciones completa
194
+ está en [`ACEPTACION-v0.1.md`](ACEPTACION-v0.1.md), sección «Desviaciones del contrato de herramientas
195
+ (§16 de v2)».
@@ -0,0 +1,105 @@
1
+ # LifeCode RAG — Proveedores de embeddings
2
+
3
+ **Fecha:** 2026-11-17 · **Estado:** contrato propuesto + alternativas a evaluar
4
+ **Restricción de esta fase:** no se descarga ningún modelo, no se instala ninguna dependencia y no se
5
+ activa ningún proveedor remoto. Este documento diseña la decisión; no la toma.
6
+
7
+ ---
8
+
9
+ ## 1. Situación actual
10
+
11
+ `lib/embed.mjs` implementa `local-hash-v1`: bolsa de tokens con hash SHA-256 a 256 dimensiones, signo por
12
+ bucket, `1+log1p(count)`, bigramas con peso 0.5 y L2. Es **léxico**, no semántico.
13
+
14
+ Consecuencia medida (benchmark v0.1.0): una paráfrasis como `instalar` contra un corpus que dice
15
+ `instalación` obtiene Recall@5 = 0.000, tanto en FTS como en híbrida. No es un defecto del código: es el
16
+ límite del modelo. La corrección es un proveedor semántico, no más magia léxica.
17
+
18
+ El valor de `local-hash-v1` sigue siendo real: cero dependencias, determinista, offline, rápido, y sirve
19
+ como red de seguridad cuando el semántico no está disponible.
20
+
21
+ ## 2. Contrato `EmbeddingProvider`
22
+
23
+ ```js
24
+ /**
25
+ * @typedef {Object} EmbeddingProvider
26
+ * @property {string} id // 'local-hash-v1' | 'onnx-multilingual-minilm-v1' | ...
27
+ * @property {number} dim
28
+ * @property {'local'|'remote'} kind
29
+ * @property {string} [license] // licencia del código y, si aplica, del modelo
30
+ * @property {(texts: string[], opts?: {signal?: AbortSignal}) => Promise<Float32Array[]>} embedBatch
31
+ */
32
+ ```
33
+
34
+ Requisitos:
35
+
36
+ - **Determinista**: mismo texto ⇒ mismo vector, mismo `id`, mismo `dim`.
37
+ - **Normalizado** (L2 = 1) o se normaliza en el adaptador; el coseno no debe depender del proveedor.
38
+ - **Lotes**: `embedBatch` acepta N textos; el adaptador decide el tamaño real.
39
+ - **Cancelable**: `signal` comprobado entre lotes.
40
+ - **Sin red por defecto**: `kind:'remote'` exige aprobación por llamada y `localOnly=false`.
41
+ - **Errores**: cualquier fallo se normaliza a `RagError('embedding-failed')`; nunca se escribe un vector
42
+ a medias.
43
+ - **Identidad versionada**: `id` incluye versión (`...-v1`). Cambiar de modelo es un `id` nuevo, no un
44
+ cambio silencioso del anterior.
45
+
46
+ ## 3. Almacenamiento y migración
47
+
48
+ La tabla `vectors` ya guarda `(chunk_key, model, dim, vec)` con `model` en la PK lógica por chunk. Reglas:
49
+
50
+ - Un chunk puede tener vectores de varios modelos (migración en caliente).
51
+ - La búsqueda usa **un** modelo: el activo en configuración; si no hay cobertura completa, se declara
52
+ `vector-index-incomplete` y la híbrida degrada a FTS.
53
+ - `reindex vectors` con un modelo nuevo es una operación de confirmación (puede tardar y ocupar CPU).
54
+ - Borrar el modelo antiguo es explícito (`reindex vectors --prune`), nunca automático.
55
+ - El esquema no cambia para añadir un proveedor: solo `model`/`dim` y la política de cuál está activo.
56
+
57
+ ## 4. Alternativas (a verificar en M6, sin instalar ahora)
58
+
59
+ | Opción | Ventajas | Costes/riesgos | Español | Estado |
60
+ |---|---|---|---|---|
61
+ | **A. ONNX Runtime + modelo multilingüe pequeño** (p. ej. familia MiniLM/E5 multilingüe, ONNX) | CPU, offline, ecosistema maduro; `onnxruntime-node` con binarios Windows | dependencia nativa (~decenas de MB), modelo 80–120 MB, licencia del modelo aparte de la del runtime; hay que verificar compatibilidad Electron/ABI | sí (modelos multilingües) | **no probado en este host** |
62
+ | **B. transformers.js (ONNX) en proceso** | JS puro sobre ONNX, sin compilar | memoria y arranque; descarga de modelo desde hub si no se vendoriza; versión de ONNX Runtime | sí | **no probado** |
63
+ | **C. node-llama-cpp + GGUF** | buenos embeddings, CPU/GPU, modelos pequeños | binario nativo, compilación/ABI, licencia del modelo; consumo de memoria | depende del modelo | **no probado** |
64
+ | **D. Windows ML / DirectML** | aceleración en Windows | API y empaquetado propios; dependencia de versión de Windows | depende | **no probado** |
65
+ | **E. API remota compatible OpenAI** (`/v1/embeddings`) | cero binarios, calidad alta | egress, coste, latencia, privacidad; requiere aprobación por llamada | sí | contrato ya previsto |
66
+ | **F. Seguir solo léxico** | cero deps | no resuelve paráfrasis | n/a | actual |
67
+
68
+ Ninguna opción se elige por intuición. La decisión es un resultado de medición, no una preferencia.
69
+
70
+ ## 5. Protocolo de evaluación (M6)
71
+
72
+ 1. Corpus congelado de `RETRIEVAL-EVALUATION.md` (120 consultas, es/en).
73
+ 2. Línea base: `local-hash-v1` (ya medida).
74
+ 3. Para cada candidato: mismo corpus, mismo chunking, mismos K; medir Recall@5/10, MRR@5/10, NDCG@10,
75
+ latencia p50/p95 de `embedBatch` y de consulta, RAM pico, tiempo de arranque.
76
+ 4. Repetir 3 veces; publicar mediana y dispersión.
77
+ 5. Criterio de promoción: mejora **medida** en Recall@10 ≥ 10 puntos absolutos sobre la paráfrasis sin
78
+ degradar latencia p95 de consulta por encima de +50 ms ni RAM por encima de +150 MB.
79
+ 6. Si ningún candidato cumple, se queda `local-hash-v1` y se dice.
80
+
81
+ ## 6. Empaquetado y licencias
82
+
83
+ - El proveedor debe poder instalarse **como dependencia opcional** del bundle, no obligatoria: quien no
84
+ la tenga sigue funcionando en modo léxico.
85
+ - Un modelo pesado no entra en el paquete npm del plugin; se vendoriza o se descarga con consentimiento
86
+ explícito y checksum publicado. `tools/check.mjs` seguirá fallando si aparece una descarga implícita.
87
+ - Se documentan dos licencias: la del **código** del runtime y la del **modelo**. Una licencia permisiva
88
+ del runtime no implica licencia del modelo.
89
+ - Sin telemetría del proveedor; sin llamadas de "comprobación de versión".
90
+
91
+ ## 7. Riesgos
92
+
93
+ | Riesgo | Mitigación |
94
+ |---|---|
95
+ | ABI nativa incompatible con Electron 44 | probar carga en el proceso host antes de comprometerse; si falla, opción B |
96
+ | Modelo que alucina similitud en español | evaluar con corpus es antes de promover |
97
+ | Aumento de tamaño del bundle | opcional + vendorizado fuera del paquete |
98
+ | Migración a medias | `model` por vector + cobertura obligatoria antes de activar |
99
+ | Egress accidental | `localOnly` por defecto; el proveedor remoto no se activa por config sin aprobación |
100
+
101
+ ## 8. Decisión pendiente
102
+
103
+ `DECISIONS-v0.2.0.md` ADR-06 fija: **no se adopta proveedor en v0.2.0; se implementa el puerto y el
104
+ arnés de evaluación**. La adopción ocurre en v0.2.1 con números. Esta es una decisión deliberada para no
105
+ vender "semántico" sin evidencia.
@@ -0,0 +1,241 @@
1
+ # LifeCode RAG — Observabilidad
2
+
3
+ **Fecha:** 2026-11-17 · **Estado:** diseño propuesto (sin instrumentación implementada)
4
+ **Principio:** métricas **agregadas**, con procedencia declarada; nunca contenido.
5
+
6
+ ---
7
+
8
+ ## 1. Límites de privacidad (no negociables)
9
+
10
+ No se persiste, bajo ninguna configuración:
11
+
12
+ - prompts del sistema o del usuario;
13
+ - respuestas del modelo;
14
+ - texto de las consultas;
15
+ - texto de los chunks recuperados como telemetría;
16
+ - conversaciones, sesiones, IDs de sesión o de agente como dimensión de métrica;
17
+ - credenciales, tokens o cabeceras.
18
+
19
+ Sí se persiste: contadores, latencias por cubo, conteos por colección y estrategia, y el resultado
20
+ `ok|error|zero-results` de una consulta. Una consulta con cero resultados incrementa un contador; su
21
+ texto se descarta al terminar la petición.
22
+
23
+ ## 2. Catálogo de métricas
24
+
25
+ Cada fila declara **procedencia**: `medido` (instrumentado en el punto de ejecución) o
26
+ `derivado` (calculado a partir de medidos), y su **método**.
27
+
28
+ | Métrica | Definición | Procedencia | Punto |
29
+ |---|---|---|---|
30
+ | `queries.agent` | consultas servidas por `lifecode_rag_search`/`context` | medido | tool execute |
31
+ | `queries.lab` | consultas del Laboratorio (separadas) | medido | `POST /retrieval` |
32
+ | `queries.zero` | consultas con 0 resultados | medido | `search()` |
33
+ | `contexts.built` | contextos devueltos por `lifecode_rag_context` | medido | `assembleContext` |
34
+ | `contexts.truncated` | contextos que no cupieron en el presupuesto | medido | `assembleContext` |
35
+ | `tokens.served` | suma de `tokens` estimados de contextos servidos | derivado | `ceil(chars/4)` |
36
+ | `tokens.corpus` | tamaño del corpus indexado en tokens estimados | derivado | `ceil(chars/4)` |
37
+ | `latency.bucket` | histograma por estrategia (`fts`/`vector`/`hybrid`) | medido | `search()` |
38
+ | `ingest.files` / `ingest.chunks` / `ingest.errors` | volumen y fallos de ingesta | medido | `ingestFiles` |
39
+ | `vectors.coverage` | chunks con vector / chunks totales, por modelo | derivado | mantenimiento |
40
+ | `fts.coverage` | filas FTS / chunks | derivado | health check |
41
+ | `audit.events` | eventos por acción y resultado | medido | `appendAudit` |
42
+ | `maintenance.runs` | reindex/forget ejecutados y su duración | medido | `maintenance` |
43
+ | `approvals.asked` / `approvals.allowed` / `approvals.rejected` | decisiones del host | medido | tool wrapper |
44
+ | `storage.bytes` | tamaño de `rag.sqlite3` + `-wal` | medido | snapshot |
45
+ | `metrics.write_failures` | escrituras de métricas fallidas (contador en memoria, volcado best-effort) | derivado | borde de telemetría |
46
+
47
+ No se mide «calidad de respuesta generada»: no hay acceso a la respuesta del modelo y no se va a inventar.
48
+
49
+ ## 3. Almacenamiento
50
+
51
+ **Una sola tabla.** Se evaluó una segunda tabla (día × métrica y otra por dimensión) y se descarta: la PK
52
+ `(day, metric, dim)` ya separa estrategias, cubos y colecciones, y una tabla extra duplicaría escrituras
53
+ sin resolver ninguna consulta que la primera no resuelva.
54
+
55
+ ```sql
56
+ CREATE TABLE metrics_daily (
57
+ day TEXT NOT NULL, -- YYYY-MM-DD (UTC)
58
+ metric TEXT NOT NULL, -- enum cerrado (§3.1)
59
+ dim TEXT NOT NULL DEFAULT '', -- enum estructurado (§3.1)
60
+ value REAL NOT NULL, -- contador o cubo; nunca texto
61
+ updated_at INTEGER NOT NULL,
62
+ PRIMARY KEY (day, metric, dim)
63
+ ) STRICT;
64
+ ```
65
+
66
+ - Un `UPSERT` por incremento (`value = value + excluded.value`), dentro de la misma transacción que la
67
+ operación cuando la operación ya escribe; si no, transacción propia de una fila.
68
+ - Escritura en lote por operación (una transacción por tool/llamada, no una por chunk).
69
+ - Latencia por cubos fijos (ms): `0-10, 10-25, 25-50, 50-100, 100-250, 250-500, 500-1000, 1000+`.
70
+ Guardar cubos, no muestras, evita crecer con el uso.
71
+ - Retención por defecto **90 días** (`metrics.retentionDays`, 7–365), con la clasificación de purga de §7.
72
+ - No hay tabla de «uso por consulta»: el ahorro se deriva de `tokens.served`, `tokens.corpus` y
73
+ `contexts.built`; guardar una fila por consulta crecería con el uso y acercaría el riesgo de perfilado.
74
+
75
+ Índices: la PK cubre `(day, metric, dim)`; serie = `WHERE metric=? AND day BETWEEN ? AND ? ORDER BY day`.
76
+
77
+ ### 3.1 Enumeraciones cerradas
78
+
79
+ `metric` es una lista cerrada; cualquier otro valor se rechaza con `invalid-metric` antes de escribir:
80
+
81
+ ```text
82
+ queries.agent | queries.lab | queries.zero | contexts.built | contexts.truncated
83
+ tokens.served | tokens.corpus | latency.bucket
84
+ ingest.files | ingest.chunks | ingest.errors
85
+ vectors.coverage | fts.coverage | audit.events | maintenance.runs
86
+ approvals.asked | approvals.allowed | approvals.rejected
87
+ storage.bytes | metrics.write_failures
88
+ ```
89
+
90
+ `dim` no es texto libre: se compone de un **tipo permitido** y un valor validado:
91
+
92
+ | Tipo | Valor permitido | Ejemplo |
93
+ |---|---|---|
94
+ | `strategy` | `fts` \| `vector` \| `hybrid` | `strategy:hybrid` |
95
+ | `bucket` | uno de los 8 cubos de latencia | `bucket:50-100` |
96
+ | `collection` | nombre de colección ya existente, `^[a-z0-9][a-z0-9._-]{0,63}$` | `collection:docs` |
97
+ | `model` | id de embedder, `^[a-z0-9][a-z0-9._-]{0,63}$` | `model:local-hash-v1` |
98
+ | `channel` | `agent` \| `lab` | `channel:lab` |
99
+ | `outcome` | `ok` \| `error` \| `zero` \| `allowed` \| `rejected` \| `asked` | `outcome:zero` |
100
+ | `action` | una acción de auditoría existente | `action:ingest` |
101
+
102
+ Reglas de validación (implementadas en `lib/metrics.mjs`, no en la UI):
103
+
104
+ 1. `metric` debe estar en la lista; `dim` debe casar `^(strategy|bucket|collection|model|channel|outcome|action):…`.
105
+ 2. `collection` y `model` se aceptan solo si ya existen en la base; si no, se descarta la métrica (no se
106
+ crea una dimensión nueva desde una petición).
107
+ 3. Se rechaza cualquier `dim` que contenga `/`, `\`, `:` extra, espacios, longitud > 96 o el texto de la
108
+ consulta (comparación con la cadena de la petición antes de descartarla).
109
+ 4. Nunca se usa la ruta de un fichero, un id de sesión/agente, una cabecera ni un token como dimensión.
110
+
111
+ ### 3.2 Agregado de `tokens.corpus`
112
+
113
+ `tokens.corpus` **no** se recalcula escaneando todos los chunks en `/snapshot`. Se mantiene un agregado
114
+ persistido en `meta`:
115
+
116
+ | Clave | Contenido |
117
+ |---|---|
118
+ | `tokens_corpus_estimate` | suma de `ceil(length(text)/4)` de los chunks vigentes |
119
+ | `tokens_corpus_chunks` | número de chunks usados en la suma |
120
+ | `tokens_corpus_seq` | `index_revision` en el momento del cálculo |
121
+
122
+ Actualización, siempre en la **misma transacción** que la mutación:
123
+
124
+ - ingesta nueva: `+= estimate(chunks insertados)`; reemplazo: `-= estimate(chunks borrados)` y `+=` los
125
+ nuevos (se hace con los valores leídos antes del `DELETE`, no después);
126
+ - `forget`: `-= estimate(chunks de la fuente)`;
127
+ - `reindex all`/`fts`: recalcula al final de la transacción global porque rebuild no cambia textos, pero sí
128
+ verifica;
129
+ - `reindex vectors`: no cambia textos → no toca el agregado.
130
+
131
+ Reconstrucción si queda inconsistente (p. ej. caída entre mutación y agregado, o edición manual):
132
+ `SELECT SUM((length(text)+3)/4), COUNT(*) FROM chunks` dentro de una transacción, y `writeMeta` con los tres
133
+ valores. Se ejecuta en `doctor` cuando `tokens_corpus_chunks != COUNT(*)` o
134
+ `tokens_corpus_seq != sources.index_revision` agregado; el resultado se marca en `/health` como
135
+ `tokens.corpus: reconstruido`. La UI muestra `≈` y la fórmula; nunca lo presenta como tokens reales.
136
+
137
+ ## 4. Instrumentación
138
+
139
+ Un único módulo `lib/metrics.mjs` con API mínima:
140
+
141
+ ```js
142
+ recordMetric(db, { metric, value = 1, dim = '', at = Date.now() })
143
+ withTiming(db, { metric, dim }, fn) // mide y registra aunque fn lance
144
+ readSummary(db, { from, to })
145
+ readSeries(db, { metric, from, to, bucket = 'day' })
146
+ ```
147
+
148
+ Reglas:
149
+
150
+ - **Nunca lanza** hacia el camino de negocio: la operación continúa aunque la métrica falle. El fallo se
151
+ contabiliza en un contador **en memoria** (`telemetryFailures`) y se escribe una sola vez, en un `try`
152
+ independiente, como `metrics.write_failures`. Si esa escritura también falla, **no se intenta registrar
153
+ el fallo del registro** (no hay recursión): queda el contador en memoria y una línea en `stderr`, y la
154
+ operación de negocio termina igual. `metrics.write_failures` jamás se cuenta a través de `recordMetric`.
155
+ - La telemetría no abre transacciones anidadas: si la operación ya escribió y la métrica falla, se pierde
156
+ la métrica, no la operación.
157
+ - El reloj se inyecta (`at`) para pruebas deterministas.
158
+ - Se llama en el borde (tools, rutas, mantenimiento), no dentro de bucles de chunk.
159
+ - Un test verifica que ninguna tabla de métricas contiene texto de consulta: se ejecuta una consulta con
160
+ una cadena única y se comprueba que esa cadena no aparece en ningún fichero del almacén.
161
+
162
+ ## 5. Derivaciones y honestidad
163
+
164
+ La UI debe poder responder «¿de dónde sale este número?». Cada tarjeta de Analítica muestra:
165
+
166
+ 1. definición en una frase;
167
+ 2. procedencia (`medido`/`derivado`);
168
+ 3. ventana temporal;
169
+ 4. si es estimado, la fórmula.
170
+
171
+ `tokens.served` y `tokens.corpus` son **estimaciones** (`ceil(chars/4)`), no tokens reales del modelo.
172
+ Se etiquetan como tales en la UI y en el benchmark. La estimación se sustituirá por conteo real cuando
173
+ exista un contrato de tokenizer en el host; hoy no lo hay.
174
+
175
+ ## 6. Consultas de lectura
176
+
177
+ `lib/query.mjs` expone:
178
+
179
+ - `metricsSummary(db, {from, to})` → `{window, queries, zeroRate, contexts, tokens, latencyP50, latencyP95, topCollections}`;
180
+ - `metricsSeries(db, {metric, from, to})` → `[{day, value}]`;
181
+ - `metricsHealth(db)` → cobertura FTS/vectores, última escritura, filas de métricas, retención.
182
+
183
+ `latencyP50/P95` se calculan a partir de los cubos con el método de §6.1; no son valores exactos.
184
+
185
+ ### 6.1 Percentiles a partir de cubos
186
+
187
+ Algoritmo (determinista, sin muestras):
188
+
189
+ 1. `N` = suma de valores de los 8 cubos de la ventana.
190
+ 2. Para `q ∈ {0.50, 0.95}`, objetivo `t = q·N`; se acumulan cubos hasta que el acumulado `≥ t`.
191
+ 3. Sea el cubo `[lo, hi)` con acumulado previo `a` y ancho `w`; la estimación es
192
+ `p = lo + w · (t − a) / count(cubo)`.
193
+ 4. El cubo abierto `1000+` se trata como `[1000, ∞)`: se devuelve `≥1000` y **no** se extrapola un valor
194
+ puntual.
195
+ 5. La precisión publicada es «± ancho del cubo»: p. ej. con `250-500` la estimación puede desviarse hasta
196
+ 250 ms. La UI muestra `≈` y el texto «estimado por histograma».
197
+
198
+ Consecuencia honesta: p95 no sirve para afirmar «cumplimos 250 ms» si el cubo que lo contiene es ancho. Para
199
+ el presupuesto de recuperación se mide con el arnés (muestras reales), no con el histograma.
200
+
201
+ ## 7. Retención y purga: clasificación única
202
+
203
+ | Operación | Quién | Requisito |
204
+ |---|---|---|
205
+ | Purga rutinaria dentro de la retención (90 d) | automática al abrir/cerrar mantenimiento | ninguna; auditada |
206
+ | Cambio de `retentionDays` (7–365) | persona desde Configuración | confirmación explícita |
207
+ | Purga anticipada (borrar antes de la retención) | persona | confirmación + motivo; auditada |
208
+ | Purga de todo el histórico | persona | **aprobación humana** por el motor de políticas |
209
+ | Borrado del almacén completo | persona | **aprobación humana** + copia previa ofrecida |
210
+
211
+ La UI no puede aprobar nada: `POST /actions` con `purgeMetrics`/`purgeAll` devuelve `approval-required` y
212
+ el host pide la aprobación con su propio diálogo. Ninguna purga se ejecuta por una ruta HTTP sin ese paso.
213
+
214
+ ### 7.1 Exportación, opt-out y desinstalación
215
+
216
+ - `metrics export` (CLI) escribe un JSON con las series; no incluye contenido.
217
+ - Desactivar analítica (`usageAnalytics: false`) detiene la escritura de `queries.*`, `tokens.*` y
218
+ `latency.*`; mantiene salud e integridad, que son diagnóstico, no uso.
219
+ - Desinstalar el plugin no borra el almacén: la UI de DSH no ejecuta borrados; se documenta la ruta.
220
+
221
+ ## 8. Pruebas exigidas (M-v0.2.0)
222
+
223
+ 1. Incremento y lectura por día/cubo; idempotencia dentro de la misma transacción.
224
+ 2. Fallo de métrica no altera el resultado de la operación.
225
+ 3. Fallo del propio `metrics.write_failures` no produce recursión ni excepción (contador en memoria).
226
+ 4. `metric`/`dim` fuera del enum se rechazan y no crean filas.
227
+ 5. Sin texto de consulta en el fichero SQLite ni en `-wal` tras una consulta única (test de privacidad).
228
+ 6. Purga respeta retención y deja auditoría; purga total sin aprobación devuelve `approval-required`.
229
+ 7. Series con huecos devuelven días sin dato como `null`, no como 0.
230
+ 8. `usageAnalytics:false` no escribe métricas de uso pero sí de salud.
231
+ 9. `tokens.corpus` sobrevive a ingesta/reemplazo/forget; tras corromper `meta` a mano, `doctor` reconstruye
232
+ y marca `reconstruido`.
233
+
234
+ ## 9. Riesgos
235
+
236
+ | Riesgo | Mitigación |
237
+ |---|---|
238
+ | Métricas que se convierten en perfilado | Sin texto, sin sesión, sin agente; retención corta; opt-out |
239
+ | Coste de escritura por consulta | UPSERT de una fila; cubos en vez de muestras |
240
+ | Números que la UI presenta como exactos | Sello `medido/derivado/estimado` obligatorio en el contrato |
241
+ | Divergencia UI/motor | El cálculo vive en `metrics.mjs`/`query.mjs`, no en el cliente |