@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.
- package/LICENSE +21 -0
- package/README.md +191 -2
- package/bin/lifecode-rag.mjs +449 -0
- package/client.js +2801 -0
- package/cordis.patch.yml +3 -0
- package/docs/ARCHITECTURE-v0.2.md +269 -0
- package/docs/AUTO-DISCOVERY.md +111 -0
- package/docs/AUTOMATION-POLICIES.md +232 -0
- package/docs/CONTRATO-v0.1.md +195 -0
- package/docs/EMBEDDING-PROVIDERS.md +105 -0
- package/docs/OBSERVABILITY.md +241 -0
- package/docs/PA-UI-0-API-CONTRACT.md +802 -0
- package/docs/PERFORMANCE-BUDGETS.md +118 -0
- package/docs/PROJECT-AWARE-ARCHITECTURE.md +580 -0
- package/docs/PROJECT-AWARE-DATA-CONTRACT.md +411 -0
- package/docs/PROJECT-AWARE-ERROR-CONTRACT.md +112 -0
- package/docs/PROJECT-AWARE-SESSION-CONTRACT.md +120 -0
- package/docs/WORKSPACE-API.md +239 -0
- package/icon.svg +7 -0
- package/index.js +198 -0
- package/lib/audit-export.mjs +70 -0
- package/lib/audit.mjs +120 -0
- package/lib/auto-context.mjs +322 -0
- package/lib/automation.mjs +214 -0
- package/lib/chunk.mjs +100 -0
- package/lib/config-resolve.mjs +119 -0
- package/lib/context.mjs +150 -0
- package/lib/conversation-events.mjs +145 -0
- package/lib/db.mjs +309 -0
- package/lib/diagnose.mjs +197 -0
- package/lib/discovery.mjs +402 -0
- package/lib/doctor.mjs +82 -0
- package/lib/embed.mjs +96 -0
- package/lib/embedders.mjs +103 -0
- package/lib/errors.mjs +227 -0
- package/lib/exec-context.mjs +238 -0
- package/lib/extract.mjs +260 -0
- package/lib/harness-workspaces.mjs +85 -0
- package/lib/hash.mjs +34 -0
- package/lib/ingest.mjs +239 -0
- package/lib/inputs.mjs +67 -0
- package/lib/library-state.mjs +252 -0
- package/lib/maintenance.mjs +113 -0
- package/lib/metrics.mjs +164 -0
- package/lib/migrate.mjs +373 -0
- package/lib/operations.mjs +132 -0
- package/lib/pa-api.mjs +517 -0
- package/lib/paths.mjs +345 -0
- package/lib/policy.mjs +125 -0
- package/lib/profile.mjs +128 -0
- package/lib/readmodel.mjs +159 -0
- package/lib/recovery.mjs +557 -0
- package/lib/registry-schema.mjs +206 -0
- package/lib/registry.mjs +406 -0
- package/lib/resolve.mjs +311 -0
- package/lib/retention.mjs +143 -0
- package/lib/revocation.mjs +124 -0
- package/lib/roots-structure.mjs +224 -0
- package/lib/schema.mjs +173 -0
- package/lib/scope-ops.mjs +379 -0
- package/lib/scope-stores.mjs +128 -0
- package/lib/search.mjs +345 -0
- package/lib/selection.mjs +150 -0
- package/lib/server.mjs +335 -0
- package/lib/session-identity.mjs +51 -0
- package/lib/sessions.mjs +343 -0
- package/lib/sync-scheduler.mjs +354 -0
- package/lib/sync.mjs +755 -0
- package/lib/tags.mjs +45 -0
- package/lib/tools.mjs +364 -0
- package/lib/trusted-roots.mjs +149 -0
- package/lib/worker-context.mjs +22 -0
- 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.
|