@designerbyron/lifecode-rag 0.0.0-stage → 1.0.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 +191 -2
  3. package/bin/lifecode-rag.mjs +449 -0
  4. package/client.js +2801 -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 +802 -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 +227 -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 +517 -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 +406 -0
  55. package/lib/resolve.mjs +311 -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 +150 -0
  64. package/lib/server.mjs +335 -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,580 @@
1
+ # Arquitectura Project-Aware RAG — PA0
2
+
3
+ **Estado:** especificación cerrada de PA0. **Nada implementado.** No se creó ninguna base de datos, no se
4
+ migró ningún almacén y no se instaló nada.
5
+ **Base:** LifeCode RAG v0.2.0 (M0—M5), almacén único por instalación.
6
+ **Contratos compañeros:** [datos](PROJECT-AWARE-DATA-CONTRACT.md) ·
7
+ [sesión](PROJECT-AWARE-SESSION-CONTRACT.md) · [errores](PROJECT-AWARE-ERROR-CONTRACT.md).
8
+ **Registro de decisiones:** `plans/PA0-DECISION-REGISTER.md`.
9
+
10
+ ## 1. Decisiones que fija esta arquitectura
11
+
12
+ | ID | Decisión humana | Consecuencia arquitectónica |
13
+ |---|---|---|
14
+ | O-PAR-1 | Contrato **v0.3** para ampliaciones; v0.1 congelado | `<scope_id>:<source_id>` es propuesta v0.3, no se implementa; v0.1 no cambia |
15
+ | O-PAR-2 | Selección **por sesión** | `session_scope` en el registro; sin selección global; cwd solo como resolución inequívoca |
16
+ | O-PAR-3 | Bibliotecas **anidadas prohibidas** | Solo `Proyecto — Biblioteca`; grants directos; sin herencia transitiva |
17
+ | O-PAR-4 | **Un registro por perfil** | Registro y ámbitos bajo la raíz de datos del perfil; sin acceso cruzado |
18
+ | O-PAR-5 | `missing` automático **sin borrado** | `sync_state` separa `present` / `missing` / `unreadable`; olvido definitivo sigue exigiendo aprobación |
19
+ | O-PAR-6 | Máximo **8 ámbitos** por consulta | 1 proyecto + hasta 7 bibliotecas; `scope-too-many` antes de abrir almacenes |
20
+ | C7 | Auditoría **por ámbito** | Registro audita registro/grants/sesiones; cada ámbito audita lo suyo; sin `audit.jsonl` global |
21
+ | C8 | Ciclo de vida de sesión formal | Contrato de sesión completo; la selección no la crea el modelo |
22
+
23
+ ## 2. Modelo
24
+
25
+ ```
26
+ Perfil DSH
27
+ ———— registry.sqlite3 proyectos, raíces, bibliotecas, grants,
28
+ — session_scope, sync_state, auditoría del registro
29
+ ———— scopes/
30
+ —S——— prj_<ULID>/rag.sqlite3 conocimiento del proyecto + auditoría propia
31
+ ———— lib_<ULID>/rag.sqlite3 conocimiento de la biblioteca + auditoría propia
32
+ ```
33
+
34
+ - **Proyecto**: unidad de trabajo y de aislamiento. Tiene una o más raíces autorizadas.
35
+ - **Biblioteca**: conocimiento compartido entre proyectos del **mismo** registro mediante grants.
36
+ - **Ámbito** (`scope`): la unidad que se abre para recuperar. Es un proyecto **o** una biblioteca, nunca una
37
+ mezcla.
38
+ - **Grant**: permiso de lectura directo `proyecto — biblioteca`, concedido por una persona o por el host.
39
+ - **SyncState**: estado observado de una fuente dentro de una raíz; no es una orden de borrado.
40
+
41
+ La separación física de almacenes es deliberada: el aislamiento se comprueba **abriendo solo los ficheros
42
+ permitidos**, no filtrando filas con un `WHERE`. Un error de consulta no puede alcanzar datos de otro
43
+ proyecto porque no tiene su fichero abierto.
44
+
45
+ ## 3. Almacenamiento
46
+
47
+ ### 3.1 Registro
48
+
49
+ Un `registry.sqlite3` por perfil. Contiene proyectos, raíces, bibliotecas, grants, selecciones de sesión,
50
+ estado de sincronización, operaciones coordinadas y la auditoría del registro. Su SQL normativo está en el
51
+ [contrato de datos](PROJECT-AWARE-DATA-CONTRACT.md) §3.
52
+
53
+ ### 3.2 Almacenes de ámbito
54
+
55
+ Cada proyecto y cada biblioteca tienen su `rag.sqlite3` con el esquema v3 de v0.2 (fuentes, chunks, FTS5
56
+ externa, vectores, auditoría encadenada) **más** las claves de identidad en `meta`: `scope_id`, `scope_kind`,
57
+ `profile_id`, `schema_version`, `migration_version`, `store_state`, `created_at`.
58
+
59
+ Antes de leer contenido se comprueba: que el `scope_id` del fichero coincide con el solicitado, que el
60
+ `profile_id` es el del registro, que `store_state='ready'` y que la versión de esquema es la soportada. Si no,
61
+ `scope-store-corrupt` o `scope-forbidden`; nunca se "abre igualmente".
62
+
63
+ ### 3.3 Ubicación
64
+
65
+ PA0 **no inventa** una ruta física. El contrato es abstracto (`<profile_data_root>/lifecode-rag/⬦`) y su
66
+ resolución real se verifica en PA1. `LIFECODE_RAG_ROOT` sigue siendo un override explícito de desarrollo y,
67
+ si se usa, el perfil se registra para impedir mezclas.
68
+
69
+ ## 4. Identidad y rutas
70
+
71
+ Reglas completas en el [contrato de datos](PROJECT-AWARE-DATA-CONTRACT.md) §5. Resumen:
72
+
73
+ - ULID con prefijo (`prj_`, `lib_`, `rt_`, `op_`), nunca derivados de nombre o ruta.
74
+ - Ruta canónica con `realpathSync.native`; `path_key` plegada a minúsculas en Windows y **única global**.
75
+ - Rechazo de symlinks, junctions, reparse points, hardlinks de fichero y traversal.
76
+ - Raíces solapadas dentro del mismo proyecto — `root-overlap`; no se elige una.
77
+ - Archivar no borra; borrar exige operación humana con aprobación y copia.
78
+
79
+ ## 5. Sesión y resolución de ámbito
80
+
81
+ Contrato completo en [sesión](PROJECT-AWARE-SESSION-CONTRACT.md). Resumen normativo:
82
+
83
+ 1. La identidad de sesión la aporta el host (`Session.id`); el plugin no la inventa.
84
+ 2. La selección vive en el registro del perfil y sobrevive al reinicio.
85
+ 3. Sin selección, el cwd puede resolver **solo** si coincide con exactamente una raíz registrada de un
86
+ proyecto activo; si no, `scope-unresolved` / `scope-ambiguous`.
87
+ 4. Nunca hay proyecto por defecto, último usado ni "el primero".
88
+ 5. Un clon de sesión no hereda la selección.
89
+ 6. Cambiar de proyecto en una sesión no afecta a las demás.
90
+
91
+ ## 6. Bibliotecas y grants
92
+
93
+ - Permitido: `Proyecto — Biblioteca` con grant directo y explícito.
94
+ - Prohibido: biblioteca dentro de biblioteca, proyecto dentro de biblioteca, proyecto— proyecto por grants,
95
+ herencia transitiva. El esquema lo hace imposible (no existe `parent_*`).
96
+ - Los grants los crea una persona o el host; **nunca** una herramienta del modelo.
97
+ - **Punto único de autorización:** al inicio de cada consulta se resuelven sesión y proyecto, se leen los
98
+ grants vigentes y se forma la **instantánea de autorización** (proyecto + bibliotecas permitidas). Esa
99
+ instantánea es la que decide qué almacenes se abren; no se vuelve a consultar el registro a mitad.
100
+ - **Revocación durante una consulta:** los ámbitos ya abiertos terminan su recuperación local (la instantánea
101
+ los autorizó); los ámbitos aún no abiertos se omiten con `grant-revoked`. En ambos casos la respuesta se
102
+ marca `partial: true` con el error en `errors[]`; nunca se presenta éxito limpio.
103
+ - **Consultas posteriores:** la revocación es efectiva de inmediato; la biblioteca ya no entra en la
104
+ instantánea y no se abre.
105
+ - Límite: 1 proyecto + 7 bibliotecas = **8 ámbitos**; se comprueba tras verificar grants y **antes** de abrir.
106
+ Si se supera: `scope-too-many`; no se truncan bibliotecas ni se degrada a búsqueda global.
107
+
108
+ ## 7. Recuperación entre ámbitos
109
+
110
+ Algoritmo normativo:
111
+
112
+ 1. Resolver la sesión (`session-invalid` si no hay identidad).
113
+ 2. Resolver el proyecto activo (selección — cwd — error).
114
+ 3. Leer grants vigentes del proyecto.
115
+ 4. Ordenar y aplicar el límite de 8; si se supera, `scope-too-many`.
116
+ 5. Abrir **exclusivamente** los almacenes permitidos, verificando identidad y `store_state`.
117
+ 6. Ejecutar la recuperación local de cada ámbito (FTS5 BM25 + vector + RRF interno de v0.2).
118
+ 7. Fusionar los rankings de cada ámbito con RRF (k=60), pesos configurables.
119
+ 8. Aplicar MMR sobre los candidatos fusionados.
120
+ 9. Aplicar el presupuesto global de contexto.
121
+ 10. Devolver resultados con procedencia completa.
122
+
123
+ Cada resultado conserva: `scope_kind`, `scope_id`, `source_id`, `uri`, `chunk_key`, `sha256`, `indexed_at`,
124
+ además de `score`, `rrf`, `snippet`.
125
+
126
+ **La fusión es de rankings separados, no un BM25 global.** Los `bm25` de almacenes distintos no son
127
+ comparables; solo se usa su orden dentro de cada ámbito. Esto se documenta para no vender una comparabilidad
128
+ inexistente.
129
+
130
+ Casos:
131
+
132
+ - Almacén del proyecto inaccesible — falla la consulta (`scope-store-unavailable`): sin proyecto no hay
133
+ contexto válido.
134
+ - Biblioteca inaccesible/corrupta — **falla la consulta** (`scope-store-unavailable` / `scope-store-corrupt`
135
+ con `details.scopeId`). Decisión D-PA4-F-01: el contrato v0.1 no puede expresar «resultado parcial», así
136
+ que no se devuelve un resultado que parezca exhaustivo sin serlo.
137
+ - Duplicados entre ámbitos (mismo `sha256` y rango) — se conserva uno y se anota `also_in[]` con los ámbitos
138
+ restantes; no se duplica el contexto.
139
+ - Grant revocado durante la consulta: se aplica la garantía de PA4 (§17.2) — se revalida en puntos de control
140
+ y, si un ámbito autorizado deja de estarlo antes de devolver, la operación falla con `grant-revoked` y **no
141
+ entrega** nada de ese ámbito. La consulta siguiente ya no incluye la biblioteca.
142
+
143
+ Efecto del límite de 8 (medido en `eval/quality-hardening/TEST-RESULTS.md`; reconciliado 2026-11-18):
144
+ la latencia crece de forma aproximadamente lineal con el
145
+ número de almacenes abiertos; la memoria suma cachés de SQLite; el presupuesto de contexto se reparte entre
146
+ más ámbitos. La medición corresponde a PA3.
147
+
148
+ ## 8. Sincronización
149
+
150
+ Implementado en PA5 (`lib/sync.mjs`, `lib/sync-scheduler.mjs`, CLI `sync run|status`) y probado localmente.
151
+
152
+ ### 8.1 Ciclo por proyecto y raíz
153
+
154
+ 1. Comprobar que la raíz está autorizada y accesible (`assertScopeSyncable`: ámbito activo, al menos una raíz
155
+ autorizada; si la pasada la inicia una sesión, su autorización vigente también se revalida).
156
+ 2. Recorrerla de forma completa (si no se puede completar, error de sincronización y **no** se marca `missing`).
157
+ 3. Comparar metadatos y hash con `sync_state` (y con `sources.sha256` como respaldo).
158
+ 4. Ingerir de forma incremental, una transacción por fichero.
159
+ 5. Registrar errores por fichero sin abortar el resto.
160
+ 6. Actualizar `present` / `missing` / `unreadable`.
161
+ 7. Respetar el límite por pasada y la cancelación entre ficheros.
162
+ 8. Verificar el almacén tras aplicar (recuentos, huérfanos, vectores, FTS5) y fallar con
163
+ `scope-store-corrupt` si quedó incoherente.
164
+ 9. Registrar en auditoría del ámbito (`sync.run`) y del registro (`sync.run`, `sync.tick`) lo que corresponda,
165
+ y dejar el ciclo en `operations`/`operation_steps` (`kind='sync'`: `observe`, `apply`, `verify`).
166
+
167
+ Una pasada interrumpida deja la fila `started`; la siguiente la cierra como `reconciled` sin repetir trabajo
168
+ (la sincronización es idempotente por hash, pero la fila no puede quedar mintiendo).
169
+
170
+ ### 8.2 Estados y olvido
171
+
172
+ | Estado | Significado | ¿Borra? |
173
+ |---|---|---|
174
+ | `present` | Observado y con hash | No |
175
+ | `missing` | Observación **completa** de la raíz no lo encuentra | **No**; conserva fuentes, chunks, vectores, auditoría y grants |
176
+ | `unreadable` | Error de permisos, E/S o recorrido incompleto | No; no se interpreta como desaparición |
177
+ | Olvido definitivo | Acción humana aprobada | Sí, con la autorización existente de `forget` |
178
+
179
+ Reaparición: si el hash coincide, se restaura `present` sin duplicar; si cambió, se reindexa de forma
180
+ incremental. Un `missing` no revoca grants. Un renombrado se ve como `missing` del nombre viejo más alta del
181
+ nuevo (misma URI distinta); no se intenta adivinar renombrados por inodo.
182
+
183
+ ### 8.3 Programación (límite declarado)
184
+
185
+ La automatización se activa con `automation.enabled` en `config.json` y usa el temporizador de Node
186
+ (`setInterval` con `unref`), que es lo único que existe en este entorno. **No** se asume ningún hook, evento ni
187
+ temporizador de DeepSeek Harness: comprobarlo y, si existe algo mejor, integrarlo corresponde a PA6. Mientras
188
+ tanto, el ciclo se ejecuta también a mano con `node bin/lifecode-rag.mjs sync run`.
189
+
190
+ ## 9. Auditoría por ámbito (C7)
191
+
192
+ Estructura normativa:
193
+
194
+ - `registry.sqlite3`: auditoría del registro (perfil, proyectos, raíces, bibliotecas, grants, sesiones,
195
+ migraciones, operaciones coordinadas).
196
+ - `scopes/prj_<id>/rag.sqlite3`: auditoría propia del proyecto (ingesta, olvido, reindexación, consultas que
197
+ se registren, errores).
198
+ - `scopes/lib_<id>/rag.sqlite3`: auditoría propia de la biblioteca.
199
+
200
+ **No hay `audit.jsonl` global** que contradiga el aislamiento. Si se exporta JSONL, es por almacén y derivado.
201
+
202
+ Campos por evento (en cada almacén): `seq` (auto), `at`, `actor` (`human|host|model|automation`),
203
+ `session_id`, `action`, `target`, `outcome` (`ok|failed|denied|skipped`), `detail`, `prev_hash`, `hash`.
204
+
205
+ Cada almacén tiene su propia cadena; una cadena rota se detecta al abrir y produce `scope-store-corrupt` (o
206
+ `registry-corrupt`). No se repara sola.
207
+
208
+ **No hay atomicidad entre varios almacenes.** Las operaciones que tocan registro + ámbito (migración,
209
+ creación de ámbito, borrado con copia) se registran como **operaciones coordinadas** en
210
+ `operations(id, kind, state, started_at, finished_at, detail)` con estados `started — committed | failed |
211
+ reconciled`, y sus pasos en `operation_steps(operation_id, step, state, effect_key, updated_at)`.
212
+
213
+ Reconciliación (normativa, sin ejecutarse en PA0):
214
+
215
+ 1. **Detección:** al abrir el registro, toda fila `operations.state='started'` es una operación incompleta. No
216
+ se ignora ni se borra: bloquea las operaciones nuevas hasta reconciliarse (o se reconcilia en la misma
217
+ apertura, según PA1).
218
+ 2. **Identificación de efectos:** cada paso tiene `effect_key` (por ejemplo `scope:prj_⬦:created`); antes de
219
+ repetirlo se comprueba si el efecto ya existe. Las comprobaciones son de solo lectura.
220
+ 3. **Idempotencia:** los pasos repetibles (crear directorio, copiar fichero verificado por hash, escribir
221
+ metadatos) se reejecutan solo si su `effect_key` no está aplicado. Los pasos no idempotentes (borrar,
222
+ mover) no se repiten a ciegas: si su estado es dudoso, la operación pasa a `failed` y se restaura desde la
223
+ copia.
224
+ 4. **Rollback:** si el paso fallido no puede completarse, se descarta lo nuevo y se conserva el original; el
225
+ rollback también registra pasos y su propio `effect_key`, para que sea repetible.
226
+ 5. **Cierre:** la operación termina en `committed` (todos los pasos `done`), `failed` (rollback aplicado) o
227
+ `reconciled` (interrupción resuelta sin rollback). Cada transición escribe auditoría en el registro.
228
+ 6. **Evidencia:** el `detail` guarda ids, hashes y códigos; nunca contenido de documentos.
229
+
230
+ Un fallo a mitad deja estado parcial explícito; no se presenta como transacción única.
231
+
232
+ La auditoría no guarda prompts, respuestas completas ni contenido sensible de documentos; solo referencias
233
+ (ids, rutas relativas, hashes, códigos).
234
+
235
+ ## 10. Errores
236
+
237
+ Contrato completo en [errores](PROJECT-AWARE-ERROR-CONTRACT.md): familias selección/autorización/integridad/
238
+ infraestructura/sincronización y 16 códigos, incluidos `scope-*`, `registry-*`, `scope-store-*`,
239
+ `session-*`, `grant-revoked` y `sync-root-unavailable`. Regla: nunca un error de seguridad convertido en
240
+ resultado vacío.
241
+
242
+ ## 11. Compatibilidad y versionado
243
+
244
+ - Las **siete herramientas v0.1 no cambian**: mismos nombres, parámetros, salidas y semántica de `collection`.
245
+ - No se añaden parámetros a v0.1; el ámbito se resuelve internamente.
246
+ - `<scope_id>:<source_id>` es una **propuesta para v0.3**, no implementada. Cambia la forma de una referencia
247
+ pública y por eso no puede colarse como compatible.
248
+ - v0.3 exigirá contrato propio, pruebas de compatibilidad y autorización posterior. PA0 no lo implementa ni
249
+ afirma compatibilidad.
250
+ - El almacén v3 de v0.2 se conserva como formato de cada ámbito; no se cambia el esquema dentro de PA0.
251
+
252
+ ## 12. Migración desde el almacén único v0.2 (solo especificación)
253
+
254
+ No se ejecuta en PA0. Pasos obligatorios para PA1:
255
+
256
+ 1. **Inspección** del almacén v0.2 existente (apertura en solo lectura, `integrity_check`, recuentos).
257
+ 2. **Copia de seguridad** verificada (hash) fuera del almacén operativo.
258
+ 3. **Validación** de integridad de la copia.
259
+ 4. **Recuentos** de `sources`, `chunks`, `vectors`, eventos de auditoría; comparación posterior.
260
+ 5. **Creación explícita** de un proyecto por defecto (nombre y raíz confirmados por una persona).
261
+ 6. **Autorización humana** de las raíces que se registrarán; ninguna raíz se deduce del contenido.
262
+ 7. **Copia** de fuentes/chunks/vectores hacia el almacén del proyecto, conservando `chunk_key` y hashes.
263
+ 8. **Verificación de igualdad** (criterios obligatorios, todos deben cumplirse): recuentos exactos de
264
+ `sources`, `chunks`, `vectors` y eventos de auditoría; igualdad de `sha256` por fuente; igualdad del hash
265
+ canónico del texto concatenado por `chunk_key`; `PRAGMA integrity_check` = `ok` en el destino; FTS con
266
+ `integrity-check` = `ok` y mismo número de coincidencias de una consulta de control; cadena de auditoría
267
+ verificada de extremo a extremo; `schema_version`/`application_id` coherentes. Cualquier diferencia —
268
+ rollback, no "aceptar casi igual".
269
+ 9. **Conservación del original**; no se borra ni se mueve.
270
+ 10. **Rollback** documentado: si falla la verificación, se descarta el almacén nuevo y se sigue usando el
271
+ original intacto.
272
+
273
+ La migración no crea bibliotecas ni grants por su cuenta. Un almacén migrado queda con auditoría propia
274
+ iniciada y una entrada de operación `migrate` en el registro.
275
+
276
+ ## 13. Lo que PA0 NO afirma
277
+
278
+ - En PA0 no estaba implementado: ni registro, ni ámbitos, ni resolución, ni grants, ni sincronización.
279
+ (PA1 implementó registro y migración; PA2, identidad de sesión, `session_scope`, resolución y grants.)
280
+ - La matriz mantiene **0 PASS en host**; lo probado en PA1/PA2 es local, con raíces temporales.
281
+ - La ruta por perfil está resuelta en PA1, pero el perfil real se instaló en M6 **sin registro Project-Aware**: no se inventó proyecto ni raíz (reconciliado 2026-11-18).
282
+ - El temporizador permanente no está probado en el host.
283
+ - La inyección automática previa a la respuesta sigue **BLOCKED** por falta de hook del host.
284
+ - No se ha abierto, creado, migrado ni movido ningún almacén operativo.
285
+
286
+ ## 14. Riesgos residuales
287
+
288
+ | Riesgo | Mitigación declarada |
289
+ |---|---|
290
+ | Escribir datos del plugin en una raíz de perfil no verificada | Contrato abstracto + verificación en PA1; override explícito para desarrollo |
291
+ | Crecimiento de latencia con 8 ámbitos | Presupuesto medido en PA3; límite duro y error explícito |
292
+ | Deriva entre registro y almacenes | Operaciones coordinadas + reconciliación + `integrity_check` |
293
+ | Complejidad de sesiones (clonado, reinicio) | Contrato de sesión con casos de prueba obligatorios en PA2 |
294
+ | Migración destructiva | Copia, verificación, conservación del original y rollback |
295
+ | Falsa sensación de semántica | El proveedor por defecto sigue siendo léxico; la matriz lo declara |
296
+
297
+ ## 15. Decisiones abiertas para PA1/PA3
298
+
299
+ - **O-PA0-1**: **cerrada** en el contrato de datos §3: una única tabla `roots`, con la pertenencia garantizada
300
+ por `CHECK` de prefijo, disparadores de existencia/inmutabilidad y una **FK compuesta** desde `sync_state`
301
+ que fija el ámbito de cada fila al de su raíz. El borrado de ámbitos con raíces queda bloqueado por
302
+ disparador (`scope-has-roots`).
303
+ - **O-PA0-2**: **resuelta en PA1** con un mapeo verificable y sin rutas inventadas: `LIFECODE_RAG_ROOT`
304
+ (anulación explícita) o `$DSH_HOME/lifecode-rag/profiles/<profileKey>/`, donde `profileKey` sale de
305
+ `DSH_PROFILE` o del nombre de `DSH_PROFILE_DIR` (nunca de una ruta fija). Comprobado en el entorno real:
306
+ `DSH_HOME` y `DSH_PROFILE_DIR` existen; `$DSH_HOME/lifecode-rag` no existe, así que **no se creó ningún
307
+ registro en el perfil real** en PA1 (M6 no autorizado). La creación se probó con raíces temporales idénticas
308
+ en esquema (`lib/profile.mjs`, `tests/registry.test.mjs`).
309
+ - **O-PA0-3**: retención de filas `session_scope` expiradas (propuesta: 90 días).
310
+ - **O-PA0-4**: transiciones válidas de `store_state` y quién puede moverlas.
311
+ - **O-PA0-5**: presupuesto de latencia y memoria para 8 ámbitos.
312
+
313
+ ## 16. Estado de implementación (PA1 + PA2 + PA3)
314
+
315
+ | Pieza | Módulo | Estado |
316
+ |---|---|---|
317
+ | Raíz de perfil y rutas | `lib/profile.mjs` | Implementado, probado local |
318
+ | Registro (proyectos, bibliotecas, raíces, auditoría) | `lib/registry.mjs`, `lib/registry-schema.mjs` | Implementado, probado local |
319
+ | Migración reversible del almacén único | `lib/migrate.mjs` | Implementado, probado local (origen intacto) |
320
+ | Identidad de sesión | `lib/session-identity.mjs` | Implementado; `agent.id` + perfil; sin host real |
321
+ | Selección por sesión y ciclo de vida | `lib/sessions.mjs` | Implementado, probado local |
322
+ | Resolución fail-closed | `lib/resolve.mjs` | Implementado, probado local |
323
+ | Grants y límite de 8 ámbitos | `lib/sessions.mjs` | Implementado, probado local |
324
+ | Apertura de almacenes de ámbito y recuperación multi-ámbito | `lib/scope-stores.mjs`, `lib/scope-ops.mjs` | Implementado, probado local |
325
+ | Contexto de ejecución autorizado de las siete herramientas | `lib/exec-context.mjs` | Implementado, probado local; identidad de host real no ejercitada |
326
+ | Integración de las siete herramientas con el dominio | `lib/tools.mjs` | Implementado; contrato v0.1 sin cambios |
327
+ | Sincronización incremental | PA5 | **implementada y probada localmente** (reconciliado 2026-11-18) |
328
+
329
+ El adaptador de identidad es el único punto que depende de la forma de `Agent`; si el host cambia
330
+ `agent.id`, se ajusta ahí y el resto del dominio no cambia. La resolución **no** abre almacenes: devuelve
331
+ la selección efectiva con sus raíces y `withAuthorizedContext` decide qué abrir, en qué orden y qué
332
+ errores son parciales.
333
+
334
+ ### 16.1 Integración PA3 (siete herramientas)
335
+
336
+ | Herramienta | Ámbitos | Escritura | Regla |
337
+ |---|---|---|---|
338
+ | `ingest` | sólo proyecto | sí | expande y clasifica antes de abrir; aprobación si la ruta cae fuera de las raíces del proyecto |
339
+ | `search` | proyecto + bibliotecas concedidas | no | agrega por `score`; si un ámbito autorizado no se puede consultar, la operación falla en cerrado (PA4-F) |
340
+ | `context` | proyecto + bibliotecas concedidas | no | mismo conjunto; presupuesto y MMR globales; citas con `scopeId`/`scopeKind` internos |
341
+ | `get` | todos los efectivos | no | `ref` debe resolver en **un** ámbito; 0 — `source-not-found`, —0—2 — `ambiguous-ref` |
342
+ | `list` | sólo proyecto | no | una biblioteca no se enumera como si fuera del proyecto |
343
+ | `forget` | sólo proyecto | sí | nunca borra una biblioteca; si `ref` vive allí — `library-read-only`; aprobación con fuente y ámbito exactos |
344
+ | `reindex` | sólo proyecto | sí | reconstruye FTS/vectores del proyecto; aprobación siempre |
345
+
346
+ Cada `execute` pasa por `withAuthorizedContext`, que exige `exec.agent`, valida el perfil, resuelve la
347
+ sesión y los ámbitos, abre el registro y sólo entonces permite `ctx.open(scope)`. No hay ruta alternativa
348
+ que abra un almacén: `lib/tools.mjs` no importa `openDatabase` desde PA3.
349
+
350
+ ## 17. PA4 — robustez operativa, revocación y recuperación
351
+
352
+ PA4 añade cuatro mecanismos al camino de ejecución, sin cambiar el contrato público v0.1.
353
+
354
+ ### 17.1 Estados de almacén y recuperación
355
+
356
+ `lib/library-state.mjs` clasifica cada almacén antes de usarlo, en sólo lectura y sin crear ni migrar:
357
+
358
+ | Estado | Cómo se detecta | ¿Se puede servir? |
359
+ |---|---|---|
360
+ | `present` | fichero, `application_id`, versión e identidad correctos | sí |
361
+ | `missing` | no existe el directorio o el fichero | no (nunca equivale a «vacío») |
362
+ | `unreadable` | EACCES/EPERM, o la ruta es un enlace | no; no se cuarentena a ciegas |
363
+ | `corrupt` | no es SQLite, `quick_check`/`foreign_key_check` falla, identidad incoherente | no |
364
+ | `unavailable` | bloqueado por otra conexión, o `store_state='migrating'` | no, pero reintentable |
365
+ | `recovering` | hay un staging `.recovery-*` en curso | no |
366
+ | `recovered` | marcado tras una recuperación verificada | sí |
367
+
368
+ `lib/recovery.mjs` planifica (`none|blocked|rebuild|reinit`) y ejecuta en un directorio **staging**:
369
+ copia las tablas autoritativas (`sources`, `chunks`, `source_tags`, `audit`; también `metrics_daily` y
370
+ `policies`), regenera vectores (sólo con el embedder local determinista: con un proveedor remoto la
371
+ recuperación se rechaza en vez de pedir red), reconstruye FTS5 y lo comprueba, añade la entrada de auditoría
372
+ de la recuperación y **verifica la cadena ya con esa entrada**, compara digest de datos y recuentos, y sólo
373
+ entonces hace el intercambio: el original pasa a `<scopeDir>.quarantine-<stamp>` y el staging ocupa su sitio.
374
+ `rollbackRecovery` aparta el intento fallido a `.failed-<stamp>` y restaura la cuarentena. Nada se borra.
375
+
376
+ ### 17.2 Revocación efectiva (garantía y latencia)
377
+
378
+ La autorización es una **instantánea** al abrir el contexto, y `ctx.revalidate()` la refresca en puntos
379
+ declarados: antes de abrir cada ámbito, antes de cada fichero de una ingesta, y **antes de devolver** el
380
+ resultado de `search`, `context`, `get`, `list`, `forget` y `reindex`. Si en ese punto un ámbito ya no está
381
+ autorizado, la operación falla con `grant-revoked` (`details.reason: 'revoked-during-operation'`) o con
382
+ `session-expired`/`scope-forbidden` y no devuelve nada.
383
+
384
+ **Latencia real:** la revocación se percibe como máximo en el siguiente punto de control, es decir al
385
+ terminar la consulta en curso o el fichero en curso. Un `embed` remoto lento o una consulta FTS larga no se
386
+ interrumpen desde otra conexión; SQLite no ofrece cancelación cruzada. La garantía es «no se entrega
387
+ resultado de un ámbito revocado», no «la consulta se aborta en el acto». `exec.signal` se comprueba en los
388
+ mismos puntos y en el bucle de vectores: una cancelación del host sí corta entre chunks.
389
+
390
+ **Límite de atomicidad:** lo ya confirmado no se revierte. Una ingesta de dos ficheros que pierde el grant en
391
+ el segundo deja el primero indexado (auditado como `ingest`) y no escribe el segundo; el error `grant-revoked`
392
+ lo declara. Repetir un efecto destructivo con resultado incierto está prohibido por `operation-uncertain`.
393
+
394
+ ### 17.3 Raíces: protección estructural
395
+
396
+ `lib/roots-structure.mjs` canonicaliza con `realpathSync.native` (no sólo normalizando la cadena), rechaza
397
+ enlaces/junctions/reparse points (`root-symlink`), detecta duplicados y solapes padre/hijo al registrar
398
+ (`root-overlap`) y revisa las raíces ya registradas en `registryIntegrity` (`rootConflicts`). `addRoot`
399
+ valida antes de insertar, y `path_key` guarda la ruta canónica. `assertRootUnchanged` detecta que el destino
400
+ real cambió después del registro (`root-changed`).
401
+
402
+ **Límites declarados:** Node no distingue junction de enlace de directorio (`lstat.isSymbolicLink()` es
403
+ `true` en ambos), así que se rechazan los dos; un symlink de directorio requiere Developer Mode en Windows y
404
+ la prueba usa junctions. Los reparse points de proveedor (OneDrive/DFS) no son identificables con la API de
405
+ Node: se mitiga comparando la ruta canónica en cada uso y fallando en cerrado, no pretendiendo detectarlos.
406
+
407
+ ### 17.4 Operaciones interrumpidas y retención
408
+
409
+ `lib/operations.mjs` usa el ledger PA0: `started` al empezar, pasos con `effect_key` idempotente, cierre
410
+ `committed` sólo si todos los pasos están `done` (si no, `operation-uncertain`). `assertNoInterruptedOperation`
411
+ bloquea repetir un efecto destructivo cuyo resultado se desconoce; `reconcileInterruptedOperations` **sólo
412
+ cierra la fila** con la conclusión documentada y nunca reejecuta el trabajo. La recuperación escribe su
413
+ operación `recovery` con pasos `inspect|stage|verify|swap`.
414
+
415
+ `lib/retention.mjs` es un **planificador** sin ninguna función de borrado: calcula candidatos
416
+ (`session_scope` expiradas, operaciones cerradas, métricas diarias) y lo que está protegido (sesiones activas,
417
+ operaciones abiertas, auditoría del registro), y exporta cortes verificados de la auditoría a JSONL con su
418
+ `sha256`. No se compacta ni se elimina auditoría en PA4.
419
+
420
+ ### 17.5 Concurrencia medida (ocho ámbitos, host local Windows)
421
+
422
+ Windows 11, Node 24.21.0, SQLite 3.53.4, WAL, `busy_timeout=5000`, `synchronous=FULL`. Medido en
423
+ `lifecode-rag/tests/concurrency.test.mjs` (repetible con `node --test tests/concurrency.test.mjs`):
424
+
425
+ | Medida | Valor observado | Umbral de la prueba |
426
+ |---|---|---|
427
+ | Resolución de 8 ámbitos | —0—7—8 ms | < 500 ms |
428
+ | `search` sobre 8 ámbitos | —0—36—37 ms | < 4000 ms |
429
+ | Escritura bloqueada por otra conexión | falla como `store-busy` reintentable tras `busy_timeout` | < 20 s |
430
+ | Fuga de conexiones | 8/8 directorios borrables tras cerrar | sin excepciones |
431
+
432
+ Los umbrales son de regresión, no objetivos de producto: se fijan muy por encima de lo medido para detectar
433
+ un cambio de orden de magnitud (una apertura por ámbito que pase de perezosa a eager, un N+1 de consultas),
434
+ no para afirmar un rendimiento.
435
+
436
+ ---
437
+
438
+ ## 18. PA6 — integración con el host real
439
+
440
+ Esta sección fija con qué interfaces del host cuenta la integración y cuáles **no** existen en esta
441
+ instalación. Todo lo afirmado aquí está verificado contra DeepSeek Harness `0.2.2-rc.3`
442
+ (`cordis_inspect_query` y la documentación dentro de `app.asar`), no supuesto.
443
+
444
+ ### 18.1 Interfaces verificadas
445
+
446
+ | Capacidad | Interface |
447
+ |---|---|
448
+ | Identidad de sesión | `Agent.id: SessionId`, disponible en `agent/pre-step` y en `ToolRunContext.agent` |
449
+ | Directorio de trabajo | `workingDirectory.get(session)`, `.ensure(agent, signal)`, `.set(agent, path, signal)` |
450
+ | Herramientas | `ctx.tools.register(definition)` (devuelve disposer); `ToolRunContext` con `callId`, `agent`, `signal` |
451
+ | Cancelación | `exec.signal` / `payload.signal` (AbortSignal) |
452
+ | Aprobaciones | `approval.request({agent, toolName, callId, reason, signal})` — `allowed-once` \| `rejected` \| `cancelled` \| `unavailable` |
453
+ | Temporizador | `ctx.timer.interval(callback, delay)` — disposer |
454
+ | API del Workspace | `webServer.register({kind:'prefix', path, handler})` |
455
+ | Eventos | `agent/created`, `agent/pre-step`, `agent/turn-stopping`, `tools/pre-execute`, `tools/post-execute` |
456
+
457
+ ### 18.2 Contexto antes de la respuesta
458
+
459
+ El plugin usa `agent/pre-step` porque es el único punto que **entra en la petición en curso** y trae
460
+ identidad de sesión. `agent.inject()` está documentado como «next pre-step» y puede perderse la
461
+ petición actual (`docs/subsystems/core.md:135-143`); `ctx.systemPrompt.context()` sólo recibe
462
+ `{scope, signal}`, sin sesión, y no permite resolver el ámbito sin inventar correlación.
463
+
464
+ Reglas del hook:
465
+
466
+ - sólo `payload.step === 1`, y sólo si el último mensaje es un prompt humano (`source.kind === 'user'`);
467
+ - dedupe por `(sessionId, turn, digest)` con 64 turnos por sesión, sin estado compartido entre sesiones;
468
+ - puerta léxica antes de recuperar: `searchScopes(..., {limit:1, strategy:'fts'})`; sin coincidencia
469
+ léxica no se construye contexto;
470
+ - el mensaje es `{id: uuid, role:'user', content:[{type:'text',text}], source:{kind:'lifecode-rag', form:'recall'}}`,
471
+ construido sin importar `@deepseek-ai/*`;
472
+ - cualquier error se captura: el turno continúa sin contexto.
473
+
474
+ `config.autoContext` nace **desactivado** (`enabled:false`) para no alterar el comportamiento público
475
+ v0.1 de forma silenciosa; al activarlo, `budgetTokens` no puede superar el presupuesto de `context`.
476
+
477
+ ### 18.3 Bridge de hooks Claude-Code
478
+
479
+ No está operativo en esta instalación: `include:hooks-claude-code` aparece `enabled:true` con
480
+ `fiberPhase:null`, y en un perfil gestionado por CLI falla al importar
481
+ (`ERR_MODULE_NOT_FOUND`). No se instala ni se emula; si el usuario lo activa en el futuro, convivirá
482
+ con `agent/pre-step` sin duplicar, porque el estado de dedupe es por sesión y turno.
483
+
484
+ ### 18.4 Programación de la sincronización
485
+
486
+ `index.js` obtiene `ctx.get('timer')` y pasa `interval = (cb, ms) => timer.interval(cb, ms)` a
487
+ `createSyncScheduler`. El planificador usa `setInterval(...).unref()` únicamente cuando no hay host.
488
+ `statusSnapshot().timer` distingue `host:ctx.timer.interval` de `node:setInterval`, así que la
489
+ diferencia es observable y no se declara como si fuera lo mismo.
490
+
491
+ ### 18.5 Ciclo de vida y convivencia con v0.2
492
+
493
+ La automatización del almacén único v0.2 sólo se monta si `rag.sqlite3` ya existe en la raíz del
494
+ perfil (`existsSync(storePaths(root).database)`): un perfil Project-Aware nuevo no recibe un almacén
495
+ legado vacío y no compite con la sincronización por ámbitos.
496
+
497
+ ### 18.6 Lo que PA6 no afirma
498
+
499
+ - No hay verificación con turno real del modelo: el CLI no tiene credencial
500
+ (`MISSING_CREDENTIAL`) y exportarla usaría el secreto del usuario fuera de su store. Esa prueba se
501
+ ejecuta en M6 sobre el perfil de la aplicación.
502
+ - El tick del temporizador dentro del escritorio y la cancelación real del host se verifican en M6.
503
+ - El bridge de hooks Claude-Code no existe aquí; no se declara como integrado.
504
+
505
+ ## 19. Hardening de calidad (2026-11-18)
506
+
507
+ Revisión integral de PA0–PA6/M6 con auditoría delegada y correcciones con regresión. Decisiones que
508
+ cambian contratos internos (ADR en `eval/quality-hardening/AUDIT-REPORT.md`):
509
+
510
+ - **D-PA6-09 — una sola raíz de datos.** Las herramientas y el programador de sincronización usan
511
+ `profileRoot(env)`; la raíz heredada (`ragRoot`) queda sólo para la automatización v0.2 y su API,
512
+ que además sólo se registra si existe el almacén legado. Antes, el scheduler buscaba el registro en
513
+ la raíz legada y la API servía otro almacén que las herramientas.
514
+ - **D-PA6-10 — presupuesto del contexto automático.** `autoContext.timeoutMs` (2 000 ms por
515
+ defecto, 100–15 000) y carrera con `signal`: el hook abandona y devuelve `null` en vez de
516
+ bloquear el turno. El trabajo abandonado termina por su propio timeout; es un límite declarado.
517
+ - **D-PA6-11 — sin egreso desde el hook.** El contexto automático sólo usa `local-hash-v1`; con
518
+ proveedor remoto degrada a FTS y MMR local. El egreso sigue exigiendo aprobación por llamada en las
519
+ herramientas.
520
+ - **D-PA5-A-13 — `sync_state` se publica después de ingerir.** Antes se marcaba `present` dentro
521
+ del callback de autorización: un corte dejaba el hash nuevo sin fuente y la pasada siguiente lo
522
+ trataba como «sin cambios». El resultado se reconcilia con el almacén si la ingesta se interrumpe.
523
+ - **D-PA4-C-06 — identidad de perfil inyectiva.** `profileKey` añade un sufijo `sha256` cuando el
524
+ saneado pierde información; dos perfiles no pueden compartir directorio, registro ni auditoría.
525
+ - **D-PA0-11 — auditoría del registro transaccional.** `appendRegistryAudit` escribe cabeza, hash,
526
+ evento y `meta` dentro de una transacción `IMMEDIATE`; dos conexiones ya no rompen la cadena.
527
+
528
+ Límites vigentes: la revocación no es instantánea (se garantiza en los puntos de control), el
529
+ contexto automático no se ha ejercitado con datos reales, y la programación periódica se verificó con
530
+ el temporizador del host inyectado, no con un tick observado en producción.
531
+
532
+ ## 20. M6.7 — sincronización periódica controlada
533
+
534
+ El programador Project-Aware vive en `lib/sync-scheduler.mjs` y sólo se apoya en el temporizador del
535
+ host: `ctx.timer.interval(callback, delay)`. Dentro del host no hay respaldo a `setInterval` global,
536
+ porque un intervalo global sobrevive al teardown del plugin y seguiría escribiendo después de una
537
+ recarga. Si el servicio `timer` no existe, `start()` devuelve `{started:false, reason:'no-timer'}` y
538
+ `status().lastError` lo refleja; nunca se finge un programador activo.
539
+
540
+ ### 20.1 Política efectiva
541
+
542
+ | Parámetro | Valor | Límite | Por qué |
543
+ |---|---:|---|---|
544
+ | `intervalMs` | 900 000 (15 min) | 5 000–3 600 000 | cadencia operativa |
545
+ | `tickBudgetMs` | 2 000 | 250–120 000 | el tick corre en el proceso del host |
546
+ | `maxFilesPerRun` | 25 | 1–1 000 | pasada acotada y reanudable |
547
+ | Ámbitos | `activeSyncScopes` del perfil | — | sólo proyectos y bibliotecas activos |
548
+ | Concurrencia | 1 por ámbito | — | guarda `running` + `skippedTicks` |
549
+ | Reintentos | 0 inmediatos | — | backoff exponencial hasta 8 intervalos |
550
+
551
+ ### 20.2 Presupuesto y finalización
552
+
553
+ El presupuesto se comprueba **entre ficheros** (`authorize` lanza `cancelled` con
554
+ `details.reason = 'budget-exhausted'`), nunca dentro de una transacción: lo confirmado queda y lo no
555
+ empezado no se marca. `summary.stop_reason` ∈ `complete | file-limit | budget | cancelled | error`, y
556
+ `summary.outcome` ∈ `ok | partial | skipped | failed`. El ledger escribe `committed` cuando hay efectos
557
+ confirmados aunque la pasada sea parcial —alcanzar el límite o el presupuesto no es un fallo— y
558
+ `failed` sólo con error real o cancelación; `detail.complete` conserva la distinción.
559
+
560
+ ### 20.3 Exclusiones por nombre (M6.7 §5.1)
561
+
562
+ `lib/policy.mjs#isSensitiveName` añade una defensa en profundidad por patrón de nombre
563
+ (`.env*`, `*.pem|key|pfx|p12|jks|keystore`, `id_rsa`, `secrets.*`, `credentials.*`, `.npmrc`,
564
+ `.netrc`, `.pgpass`). Se excluye **antes de leer** y se cuenta como `sensitive`; no se marca
565
+ `unreadable` ni se reintenta. No sustituye a la medición de M6.5 ni es un gestor de secretos: es una
566
+ lista corta, comparada en minúsculas y sin mirar contenido.
567
+
568
+ ### 20.4 Observabilidad
569
+
570
+ `status()` devuelve `enabled`, `running`, `ticks`, `skippedTicks`, `lastTickAt`, `nextTickAt`,
571
+ `starts`, `stops`, `timerType` (`host` o `node`) y `effective` (intervalo, presupuesto y límite).
572
+ La auditoría `sync.tick` guarda recuentos (`unsupported`, `sensitive`, `partial`, `budget_exhausted`,
573
+ `budget_ms`, `max_files`) y `sync.run` el resultado por ámbito. No se registra contenido.
574
+ `bin/lifecode-rag.mjs sync report` lee esas entradas del registro sin abrir los almacenes.
575
+
576
+ ### 20.5 Lo que M6.7 no cambia
577
+
578
+ Contrato público v0.1.0 intacto (siete herramientas, mismas firmas y salidas). `autoContext` sigue
579
+ apagado por defecto. La sincronización periódica no ejecuta `forget`, no borra fuentes `missing` y no
580
+ crea proyectos, raíces ni grants.