@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
package/cordis.patch.yml
ADDED
|
@@ -0,0 +1,269 @@
|
|
|
1
|
+
# LifeCode RAG — Arquitectura v0.2
|
|
2
|
+
|
|
3
|
+
**Fecha:** 2026-11-17 · **Ámbito:** `lifecode-rag/` · **Estado:** propuesta para autorización (no implementada)
|
|
4
|
+
**Base:** v0.1.0 implementada y verificada (66/66 pruebas, `check` verde, herméticos verdes)
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## 1. Qué cambia y qué no
|
|
9
|
+
|
|
10
|
+
v0.1.0 es un **motor de herramientas**: siete tools `lifecode_rag_*` sobre un almacén SQLite propio.
|
|
11
|
+
v0.2.0 añade dos capas —**Workspace** (pestaña nativa) y **Observabilidad**— y convierte la recuperación
|
|
12
|
+
en una capacidad configurable, sin reescribir el motor.
|
|
13
|
+
|
|
14
|
+
Lo que **no** cambia:
|
|
15
|
+
|
|
16
|
+
- El contrato de las siete herramientas v0.1.0 queda congelado (ver `CONTRATO-v0.1.md`).
|
|
17
|
+
- El almacén sigue siendo SQLite propiedad exclusiva del plugin (`node:sqlite`, FTS5, vectores BLOB).
|
|
18
|
+
- Cero dependencias `@deepseek-ai/*` y cero dependencias de ejecución nuevas en esta etapa.
|
|
19
|
+
- La separación de etapas: ingesta → normalización → chunking → embeddings → índice → recuperación →
|
|
20
|
+
contexto → citas. Ninguna etapa se salta ni se fusiona para "simplificar".
|
|
21
|
+
|
|
22
|
+
Lo que **sí** cambia:
|
|
23
|
+
|
|
24
|
+
- El Workspace **no lee tablas**: consume un *read model* (`lib/query.mjs`) y una API HTTP versionada.
|
|
25
|
+
- Se añaden métricas **agregadas** y un motor de **políticas** con tres niveles de automatización.
|
|
26
|
+
- Los embeddings dejan de ser un detalle interno y pasan a ser un **puerto** con proveedores evaluables.
|
|
27
|
+
|
|
28
|
+
## 2. Principios rectores
|
|
29
|
+
|
|
30
|
+
| Principio | Consecuencia arquitectónica |
|
|
31
|
+
|---|---|
|
|
32
|
+
| Independencia de Skill Center | Sin imports, sin rutas, sin estado ni ciclos de instalación compartidos. La única coincidencia permitida es que ambos son bundles de DSH. |
|
|
33
|
+
| Local First | Ninguna ruta de código abre sockets salvo un proveedor de embeddings declarado como remoto y aprobado por llamada. |
|
|
34
|
+
| Eficiencia de tokens | Recuperación selectiva, salida compacta por defecto, presupuesto de contexto explícito y medición del ahorro. |
|
|
35
|
+
| Fail-closed | Permiso ausente, estado ambiguo o validación fallida ⇒ error tipado, nunca una escritura parcial. |
|
|
36
|
+
| Una sola fuente de verdad | SQLite es autoritativo; las proyecciones (snapshot, métricas, JSONL de auditoría) son derivadas y regenerables. |
|
|
37
|
+
| Contratos antes que pantallas | La UI consume contratos versionados; nunca conoce el esquema interno. |
|
|
38
|
+
|
|
39
|
+
## 3. Vista de capas
|
|
40
|
+
|
|
41
|
+
```mermaid
|
|
42
|
+
flowchart TB
|
|
43
|
+
subgraph Host[DSH Host]
|
|
44
|
+
T[7 tools lifecode_rag_*]
|
|
45
|
+
A[approval]
|
|
46
|
+
W[webServer]
|
|
47
|
+
S[slots client]
|
|
48
|
+
end
|
|
49
|
+
|
|
50
|
+
subgraph Core[Core — lib/]
|
|
51
|
+
ING[ingest] --> EXT[extract] --> NRM[normalize] --> CHK[chunk] --> EMB[embed port] --> IDX[index]
|
|
52
|
+
QRY[search] --> FUSE[fuse RRF] --> CTX[context MMR] --> CIT[citations]
|
|
53
|
+
POL[policy engine] -.gate.- ING
|
|
54
|
+
POL -.gate.- QRY
|
|
55
|
+
AUD[audit chain] -.append.- ING
|
|
56
|
+
AUD -.append.- MAINT[maintenance]
|
|
57
|
+
end
|
|
58
|
+
|
|
59
|
+
subgraph Store[Store]
|
|
60
|
+
DB[(SQLite: sources, chunks, chunks_fts, vectors, source_tags, audit, meta)]
|
|
61
|
+
end
|
|
62
|
+
|
|
63
|
+
subgraph Read[Read model — lib/query.mjs]
|
|
64
|
+
RM[snapshot · sources · metrics · health]
|
|
65
|
+
end
|
|
66
|
+
|
|
67
|
+
subgraph Workspace[Workspace]
|
|
68
|
+
HTTP[HTTP API /lifecode-rag/api/v1] --> CL[client.js · pestaña nativa]
|
|
69
|
+
end
|
|
70
|
+
|
|
71
|
+
T --> Core
|
|
72
|
+
IDX --> DB
|
|
73
|
+
QRY --> DB
|
|
74
|
+
MAINT --> DB
|
|
75
|
+
AUD --> DB
|
|
76
|
+
DB --> RM --> HTTP
|
|
77
|
+
W --> HTTP
|
|
78
|
+
S --> CL
|
|
79
|
+
A --> T
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Regla de dependencia, verificable con `tools/check.mjs`:
|
|
83
|
+
|
|
84
|
+
```
|
|
85
|
+
index.js → lib/tools.mjs → lib/{ingest,search,context,maintenance}
|
|
86
|
+
lib/query.mjs → lib/db.mjs (solo lectura)
|
|
87
|
+
lib/workspace-api.mjs → lib/query.mjs (+ acciones que llaman al core)
|
|
88
|
+
client.js → HTTP únicamente
|
|
89
|
+
lib/core nunca importa lib/workspace-api, lib/query, client ni nada del Workspace
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## 4. Módulos de v0.1.0 (baseline real)
|
|
93
|
+
|
|
94
|
+
| Módulo | Responsabilidad | Estado |
|
|
95
|
+
|---|---|---|
|
|
96
|
+
| `lib/paths.mjs` | Raíz, configuración, `isWithin`. | implementado |
|
|
97
|
+
| `lib/errors.mjs` | `RagError`, 25 códigos declarados. | implementado, con deuda (3 códigos emitidos sin declarar) |
|
|
98
|
+
| `lib/hash.mjs` | SHA-256, digest normalizado, `chunk_key`. | implementado |
|
|
99
|
+
| `lib/schema.mjs` | DDL v2, `application_id`, `meta`. | implementado |
|
|
100
|
+
| `lib/db.mjs` | Apertura, guardas, transacciones, FTS integrity/rebuild. | implementado |
|
|
101
|
+
| `lib/extract.mjs` | Formatos texto, HTML/JSON/JSONL/CSV, normalización. | implementado |
|
|
102
|
+
| `lib/chunk.mjs` | Chunking con solape, encabezados, offsets. | implementado |
|
|
103
|
+
| `lib/embed.mjs` | `local-hash-v1` (256 dims), coseno, BLOB. | implementado, **léxico** |
|
|
104
|
+
| `lib/ingest.mjs` | Preparación completa y sustitución atómica por fichero. | implementado |
|
|
105
|
+
| `lib/search.mjs` | FTS5/BM25, vectores, RRF k=60, filtros. | implementado |
|
|
106
|
+
| `lib/context.mjs` | MMR, presupuesto, citas. | implementado |
|
|
107
|
+
| `lib/maintenance.mjs` | forget, reindex fts/vectors/all. | implementado |
|
|
108
|
+
| `lib/audit.mjs`, `lib/audit-export.mjs` | Cadena de hashes, export JSONL, verificación. | implementado |
|
|
109
|
+
| `lib/policy.mjs` | Rutas protegidas, symlink/junction, hardlink. | implementado |
|
|
110
|
+
| `lib/tags.mjs` | Etiquetas normalizadas. | implementado |
|
|
111
|
+
| `lib/doctor.mjs` | Diagnóstico. | implementado |
|
|
112
|
+
| `lib/tools.mjs`, `index.js` | Siete tools + adaptador. | implementado |
|
|
113
|
+
|
|
114
|
+
## 5. Módulos nuevos de v0.2.0
|
|
115
|
+
|
|
116
|
+
| Módulo | Responsabilidad | No puede |
|
|
117
|
+
|---|---|---|
|
|
118
|
+
| `lib/ports/embedding.mjs` | Contrato `EmbeddingProvider` + registro. | abrir red por sí mismo |
|
|
119
|
+
| `lib/ports/extractor.mjs` | Contrato `DocumentExtractor` (futuro PDF/DOCX). | importar el core |
|
|
120
|
+
| `lib/query.mjs` | Read model: snapshot, fuentes, salud, métricas. Solo `SELECT`. | escribir, abrir transacciones de escritura |
|
|
121
|
+
| `lib/metrics.mjs` | Agregación diaria, retención, consultas de series. | guardar prompts, respuestas o texto de consulta |
|
|
122
|
+
| `lib/policies.mjs` | Evaluación de políticas y clasificación de acciones. | conceder aprobaciones |
|
|
123
|
+
| `lib/workspace-api.mjs` | Rutas HTTP v1, validación de entrada, serialización. | acceder a tablas fuera de `query.mjs` |
|
|
124
|
+
| `lib/automation.mjs` | Indexación programada dentro de raíces autorizadas, con presupuesto. | saltarse `policy`/`approval` |
|
|
125
|
+
|
|
126
|
+
## 6. Puertos y contratos
|
|
127
|
+
|
|
128
|
+
### 6.1 `EmbeddingProvider`
|
|
129
|
+
|
|
130
|
+
```js
|
|
131
|
+
/**
|
|
132
|
+
* @typedef {Object} EmbeddingProvider
|
|
133
|
+
* @property {string} id Identidad estable, p. ej. 'local-hash-v1' o 'onnx-minilm-multilingual-v1'
|
|
134
|
+
* @property {number} dim
|
|
135
|
+
* @property {'local'|'remote'} kind
|
|
136
|
+
* @property {(texts: string[], opts?: {signal?: AbortSignal}) => Promise<Float32Array[]>} embedBatch
|
|
137
|
+
*/
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Reglas: determinista para el mismo `id`+`dim`; L2-normalizado; error tipado (`embedding-failed`);
|
|
141
|
+
un proveedor remoto exige aprobación por llamada y no se activa por configuración sola. El `id` se
|
|
142
|
+
almacena junto a cada vector, de modo que dos modelos pueden convivir durante una migración.
|
|
143
|
+
|
|
144
|
+
### 6.2 `DocumentExtractor`
|
|
145
|
+
|
|
146
|
+
`{ id, extensions: string[], extract(bytes, {path, mime}) => {text, mime} }`. Los extractores registrados
|
|
147
|
+
se evalúan por extensión; ninguno puede leer fuera del buffer recibido.
|
|
148
|
+
|
|
149
|
+
### 6.3 `ReadModel`
|
|
150
|
+
|
|
151
|
+
`lib/query.mjs` expone funciones puras sobre una conexión de solo lectura:
|
|
152
|
+
|
|
153
|
+
```js
|
|
154
|
+
snapshot(db) // { counts, health, lastIndexedAt, embedders: [...] }
|
|
155
|
+
listSources(db, query) // paginado, filtros por colección/etiqueta/estado
|
|
156
|
+
sourceDetail(db, ref) // metadatos + chunks (paginados, sin texto completo por defecto)
|
|
157
|
+
metricsSummary(db, {from, to})
|
|
158
|
+
metricsSeries(db, {metric, from, to, bucket})
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Ninguna función de `query.mjs` puede recibir SQL, ni devolver filas crudas con columnas internas
|
|
162
|
+
(`prev_hash`, `vec` binario, `meta` completo).
|
|
163
|
+
|
|
164
|
+
## 7. Flujos
|
|
165
|
+
|
|
166
|
+
### 7.1 Ingesta (sin cambios de fondo)
|
|
167
|
+
|
|
168
|
+
```mermaid
|
|
169
|
+
sequenceDiagram
|
|
170
|
+
participant M as Modelo
|
|
171
|
+
participant T as lifecode_rag_ingest
|
|
172
|
+
participant P as policy
|
|
173
|
+
participant I as ingest
|
|
174
|
+
participant DB as SQLite
|
|
175
|
+
M->>T: paths / collection / tags / force
|
|
176
|
+
T->>T: expandir directorios, clasificar TODAS las rutas
|
|
177
|
+
alt ruta protegida o fuera de raíz
|
|
178
|
+
T-->>M: path-denied / approval-required (sin abrir el almacén)
|
|
179
|
+
end
|
|
180
|
+
T->>P: ¿raíz autorizada?
|
|
181
|
+
T->>I: prepareDocument (extraer, chunk, vectores)
|
|
182
|
+
I->>DB: BEGIN IMMEDIATE
|
|
183
|
+
I->>DB: upsert source + delete chunks antiguos + insert + tags + audit
|
|
184
|
+
I->>DB: COMMIT
|
|
185
|
+
I-->>T: {ingested, skipped, errors}
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
Invariante I6: toda fila de `sources` tiene ≥1 chunk. Un fallo de preparación no toca la versión anterior.
|
|
189
|
+
|
|
190
|
+
### 7.2 Recuperación y contexto
|
|
191
|
+
|
|
192
|
+
1. `queryTokens` → FTS5 (`bm25`) y vector search (coseno) en paralelo lógico.
|
|
193
|
+
2. `fuseRrf` con k=60; empates por `chunk_key`.
|
|
194
|
+
3. `assembleContext` con MMR (λ=0.7), presupuesto en tokens estimados (`ceil(chars/4)`), sin cortar chunks.
|
|
195
|
+
4. Citas `[n]` con `chunkKey`, URI, offsets.
|
|
196
|
+
|
|
197
|
+
### 7.3 Workspace
|
|
198
|
+
|
|
199
|
+
```mermaid
|
|
200
|
+
sequenceDiagram
|
|
201
|
+
participant U as Persona
|
|
202
|
+
participant C as client.js
|
|
203
|
+
participant H as /api/v1
|
|
204
|
+
participant Q as query.mjs
|
|
205
|
+
participant DB as SQLite
|
|
206
|
+
U->>C: abre pestaña
|
|
207
|
+
C->>H: GET /snapshot
|
|
208
|
+
H->>Q: snapshot(db)
|
|
209
|
+
Q->>DB: SELECT agregados (solo lectura)
|
|
210
|
+
Q-->>H: conteos, salud, proveedores
|
|
211
|
+
H-->>C: JSON (ETag)
|
|
212
|
+
C-->>U: Overview con estado real
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
El Workspace no escribe: las acciones (reindexar, olvidar, cambiar política) van por `POST /actions`,
|
|
216
|
+
pasan por el mismo evaluador de políticas y, cuando toca, por `ctx.approval.request`.
|
|
217
|
+
|
|
218
|
+
## 8. Aislamiento respecto de Skill Center
|
|
219
|
+
|
|
220
|
+
LifeCode Skill Center y LifeCode RAG comparten host, no producto. Concretamente:
|
|
221
|
+
|
|
222
|
+
- No hay imports cruzados ni rutas de estado compartidas.
|
|
223
|
+
- `PROTECTED_SEGMENTS = ['lifecode-skill-center']` sigue rechazando cualquier ruta que contenga ese
|
|
224
|
+
segmento, incluidas las copias instaladas en el perfil.
|
|
225
|
+
- El Workspace de RAG vive en su propio slot (`sidebar.panellist` id `lifecode-rag`, `main` clave
|
|
226
|
+
`lifecode-rag`); no reutiliza el id `lifecode-skill-center`.
|
|
227
|
+
- Los ciclos de instalación son independientes: dos bundles, dos filas de loader, dos versiones.
|
|
228
|
+
|
|
229
|
+
## 9. Compatibilidad con el host (evidencia)
|
|
230
|
+
|
|
231
|
+
| Capacidad | Contrato verificado | Fuente |
|
|
232
|
+
|---|---|---|
|
|
233
|
+
| Pestaña nativa | slot `sidebar.panellist` (lista, `id` direcciona el panel) + slot `main` (keyed, misma clave) | `Slots.listSubTree` en vivo; ocupantes actuales incluyen `lifecode-skill-center` |
|
|
234
|
+
| Panel activo | prop estándar `usePanelInfo` → `PanelInfo.activePanelId` (`null` = Conversación) | `dsh-client-ui-layout/src/client/service.ts` y `src/client/index.ts` |
|
|
235
|
+
| Icono de rail | props `{size, active}` del owner | catálogo del slot |
|
|
236
|
+
| HTTP | `ctx.webServer.register({kind, path, handler})`, rutas nombradas, `getOrigin()` | servicio `webServer` |
|
|
237
|
+
| Aprobaciones | `ctx.approval.request` → solo `allowed-once` concede | servicio `approval` |
|
|
238
|
+
| Working directory | `ctx.workingDirectory.ensure(agent, signal)` | servicio `workingDirectory` |
|
|
239
|
+
| Tema | tokens `--dsw-alias-*` (14 verificados) | `Theme.listTokens` |
|
|
240
|
+
| Cliente | `window.__ModuleLoader__.load({id, factory})`, React del loader | `ui-plugin.md` + precedente LSC |
|
|
241
|
+
| SQLite/FTS5 | `node:sqlite` 3.53.4 en el proceso host | sonda propia (v0.1.0) |
|
|
242
|
+
|
|
243
|
+
No se asume ninguna API por nombre: lo que no está en esta tabla se marca como no verificado en
|
|
244
|
+
`PLAN-v0.2.0.md` y se comprueba en M0 antes de escribir código.
|
|
245
|
+
|
|
246
|
+
**Ciclo de vida del panel.** El host no emite un evento de «panel seleccionado»; la señal es el hook
|
|
247
|
+
`usePanelInfo` que el runtime inyecta en el slot `main` (contrato de `dsh-client-ui-layout`). La UI lo usa
|
|
248
|
+
para detener el refresco cuando el panel no está activo (`WORKSPACE-UX.md` §5); `document.visibilityState`
|
|
249
|
+
solo cubre minimizado. Si ese hook desapareciera en una versión futura, el panel debe degradar a «sin
|
|
250
|
+
refresco automático», no a polling ciego.
|
|
251
|
+
|
|
252
|
+
## 10. Riesgos arquitectónicos
|
|
253
|
+
|
|
254
|
+
| Riesgo | Impacto | Mitigación |
|
|
255
|
+
|---|---|---|
|
|
256
|
+
| El read model se convierte en segunda lógica | Divergencia UI/motor | `query.mjs` solo agrega; los cálculos de recuperación siguen en `search`/`context` |
|
|
257
|
+
| Métricas que se vuelven vigilancia | Privacidad | Solo agregados; sin texto de consulta ni prompts; retención y borrado |
|
|
258
|
+
| Pestaña que ralentiza el escritorio | Mala experiencia | Carga diferida por sección, sin polling oculto, presupuestos medidos |
|
|
259
|
+
| Proveedor de embeddings que cambia la calidad | Regresión silenciosa | `model_id` por vector + evaluación obligatoria antes de promover |
|
|
260
|
+
| Automatización que erosiona aprobaciones | Seguridad | Tres niveles explícitos; el motor de políticas no puede conceder |
|
|
261
|
+
| Crecimiento del almacén | Coste y latencia | Retención de métricas, compactación documentada, límites por ingesta |
|
|
262
|
+
|
|
263
|
+
## 11. Decisiones abiertas
|
|
264
|
+
|
|
265
|
+
- Formato exacto del fichero de políticas (`policies.json` vs tabla `policies`): se decide en M1 con
|
|
266
|
+
criterio de atomicidad y auditoría.
|
|
267
|
+
- ¿El Workspace necesita WebSocket para progreso de ingesta larga, o basta polling bajo demanda?
|
|
268
|
+
Se mide en M3; por defecto, sin WebSocket.
|
|
269
|
+
- ¿Las métricas viven en SQLite o en un JSONL agregado? SQLite por transaccionalidad; se confirma en M1.
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
# Descubrimiento automático de proyectos y resolución por sesión
|
|
2
|
+
|
|
3
|
+
**Fecha:** 2026-11-19 · **Estado:** implementado y probado en local · **Ámbito:** `lifecode-rag`
|
|
4
|
+
|
|
5
|
+
## Qué problema resuelve
|
|
6
|
+
|
|
7
|
+
Antes, una sesión nueva sin selección explícita fallaba con `scope-unresolved` aunque su `cwd`
|
|
8
|
+
estuviera dentro de un proyecto real ya registrado, y el panel mostraba datos sintéticos como si
|
|
9
|
+
fueran el proyecto activo. Ahora el plugin puede **descubrir** proyectos dentro de una ubicación de
|
|
10
|
+
trabajo en la que el usuario confía, **registrarlos** de forma idempotente y **resolver** el proyecto
|
|
11
|
+
de la sesión por su `cwd`, sin exigir selección manual y sin ampliar por su cuenta el ámbito de lectura.
|
|
12
|
+
|
|
13
|
+
## Los cuatro conceptos (no son sinónimos)
|
|
14
|
+
|
|
15
|
+
| Concepto | Qué significa | Dónde vive |
|
|
16
|
+
|---|---|---|
|
|
17
|
+
| Workspace confiable | Ubicación de trabajo que una persona confió una vez (`trusted_roots`, máx. 32) | `meta.trusted_roots` del registro |
|
|
18
|
+
| Proyecto descubierto | Proyecto detectado por indicadores dentro de un workspace confiable | resultado de `scanWorkspace` |
|
|
19
|
+
| Proyecto registrado | Proyecto con identidad estable (`prj_…`) y raíz autorizada | tablas `projects`/`roots` |
|
|
20
|
+
| Proyecto indexado | Proyecto con almacén de ámbito y fuentes | `profiles/<perfil>/scopes/<id>/rag.sqlite3` |
|
|
21
|
+
|
|
22
|
+
Descubrir **no** indexa, **no** lee documentos y **no** autoriza lectura. La única autorización que
|
|
23
|
+
abre la puerta es `trust add --path <abs>` (por defecto con autorización de lectura) ejecutada por una
|
|
24
|
+
persona o por un mecanismo del host. Sin `readAuthorization`, la resolución automática no registra nada.
|
|
25
|
+
|
|
26
|
+
## Indicadores reconocidos
|
|
27
|
+
|
|
28
|
+
`artisan` (Laravel), `composer.json` (PHP), `package.json` (Node, clasificado por dependencias en
|
|
29
|
+
nuxt/next/vue/react/angular/svelte), `*.sln`/`*.csproj` (.NET), `pyproject.toml`/`requirements.txt`
|
|
30
|
+
(Python), `go.mod`, `Cargo.toml`, `pom.xml`, `Gemfile`, `.git` (Git), `index.html` (web). Sólo se lee
|
|
31
|
+
`package.json` (≤ 256 KiB) para clasificar; nunca ficheros de secretos (`.env*`, claves, `.npmrc`,
|
|
32
|
+
`credentials.json`, …).
|
|
33
|
+
|
|
34
|
+
Se excluyen `.git`, `node_modules`, `vendor`, `dist`, `build`, `out`, `target`, `bin`, `obj`,
|
|
35
|
+
`.next`, `.nuxt`, `__pycache__`, `.venv`, `venv`, `cache`, `tmp`, `.idea`, `.vscode`, `secrets`,
|
|
36
|
+
`.ssh`, y los enlaces simbólicos (se registran como `skipped`, no se recorren).
|
|
37
|
+
|
|
38
|
+
## Registro idempotente
|
|
39
|
+
|
|
40
|
+
`registerDiscoveredProject` se apoya en la raíz registrada (`roots.path_key`): si el proyecto ya
|
|
41
|
+
existe se actualizan sólo los metadatos (`project_discovery:<id>`: tipo, indicadores, primera/última
|
|
42
|
+
detección, raíz registrada) y se **conservan** el `id`, el almacén y las fuentes. Un cambio de ruta
|
|
43
|
+
crea una entrada nueva de descubrimiento, no reescribe el proyecto histórico. Nunca se crea un
|
|
44
|
+
almacén por descubrir.
|
|
45
|
+
|
|
46
|
+
## Resolución por sesión
|
|
47
|
+
|
|
48
|
+
1. Identidad del host (`exec.agent.id`) y perfil.
|
|
49
|
+
2. Selección explícita si existe (prevalece, incluidas raíces anidadas: gana la más específica).
|
|
50
|
+
3. Si no hay selección: `cwd` → `findProjectBoundary` (sube desde el `cwd` hasta el workspace
|
|
51
|
+
confiable, tolera directorios aún no creados) → auto-registro si hay autorización de lectura →
|
|
52
|
+
`resolveScope` normal.
|
|
53
|
+
4. Sin workspace confiable, sin autorización o fuera de toda raíz: `scope-unresolved` (nunca una
|
|
54
|
+
búsqueda global, nunca un proyecto por defecto).
|
|
55
|
+
|
|
56
|
+
## CLI
|
|
57
|
+
|
|
58
|
+
```sh
|
|
59
|
+
node bin/lifecode-rag.mjs trust add --path C:\ruta\a\mi-proyecto --read true
|
|
60
|
+
node bin/lifecode-rag.mjs trust list
|
|
61
|
+
node bin/lifecode-rag.mjs discover scan --path C:\ruta\a\mi-proyecto
|
|
62
|
+
node bin/lifecode-rag.mjs discover register --path C:\ruta\a\mi-proyecto --read true
|
|
63
|
+
node bin/lifecode-rag.mjs discover show --project prj_…
|
|
64
|
+
node bin/lifecode-rag.mjs trust remove --path C:\ruta\a\mi-proyecto
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
`trust remove` revoca la confianza sin borrar proyectos ni almacenes.
|
|
68
|
+
|
|
69
|
+
## Límites conocidos
|
|
70
|
+
|
|
71
|
+
- El panel sigue siendo **informativo** (fixtures de demostración claramente etiquetados): no hay API
|
|
72
|
+
con datos reales porque DSH no ofrece autenticación por sesión (PA-UI-0, BLOCKED). Las herramientas
|
|
73
|
+
del agente sí usan datos reales.
|
|
74
|
+
- La confianza se guarda en `meta` para no migrar el esquema; el día que haya tabla propia se migrará
|
|
75
|
+
con procedimiento reversible.
|
|
76
|
+
- No se descubren proyectos por red ni en unidades no confiadas; el escaneo es local y acotado
|
|
77
|
+
(`maxDepth` 4, `maxProjects` 200).
|
|
78
|
+
|
|
79
|
+
## Harness Open Projects (2026-11-19)
|
|
80
|
+
|
|
81
|
+
DeepSeek Harness mantiene un registro durable de *workspaces* (`ctx.workspaceRegistry`): ruta
|
|
82
|
+
canónica, título y sesiones que lo tienen abierto. El plugin lo usa como la señal de **qué
|
|
83
|
+
proyectos tiene abiertos la persona**, en vez de deducirlo de `cwd` o de confiar en una carpeta
|
|
84
|
+
contenedora:
|
|
85
|
+
|
|
86
|
+
- `lib/harness-workspaces.mjs` normaliza los workspaces vivos (`listOpenProjects`) y resuelve el
|
|
87
|
+
proyecto de una sesión (`openProjectForSession`) o el que contiene un `cwd`
|
|
88
|
+
(`openProjectForCwd`). Los workspaces cuyo directorio ya no existe (`status() !== 'ok'`) se
|
|
89
|
+
omiten.
|
|
90
|
+
- Si la sesión pertenece a un proyecto abierto, ese proyecto es el candidato aunque su `cwd`
|
|
91
|
+
apunte a la carpeta contenedora. Abrir `plugins-dhs` **no** registra `businesssuite`,
|
|
92
|
+
`carlosdiaz` ni ningún hermano.
|
|
93
|
+
- Abrir un proyecto **no es autorizar**: la lectura sigue exigiendo `trust add` sobre la ruta del
|
|
94
|
+
proyecto. Sin esa autorización la llamada falla en cerrado con `scope-unresolved`,
|
|
95
|
+
`reason: "project-not-authorized"` y el comando exacto en `details.command`.
|
|
96
|
+
- Cuando el proyecto abierto es hijo del `cwd`, la resolución va directa a su id en lugar de
|
|
97
|
+
exigir una coincidencia por prefijo.
|
|
98
|
+
|
|
99
|
+
La prueba de forma real (`eval/auto-discovery-01/scripts-harness-shape.mjs`) copia el registro
|
|
100
|
+
real con `VACUUM INTO`, lee `$DSH_HOME/storages/workspace.json` y demuestra: sin trust →
|
|
101
|
+
`project-not-authorized`; con trust sólo de `<proyecto>` → resuelve ese proyecto con `cwd`
|
|
102
|
+
`<checkout>`; ningún hermano registrado; el registro y el almacén reales no cambian
|
|
103
|
+
(hashes antes/después en `16-harness-shape.txt`).
|
|
104
|
+
|
|
105
|
+
### Límite de esta entrega
|
|
106
|
+
|
|
107
|
+
El agente que atiende esta sesión ejecuta el código cargado en el arranque del host. Este módulo y
|
|
108
|
+
la resolución por proyectos abiertos se escribieron **después** de ese arranque, así que la
|
|
109
|
+
verificación en vivo del host queda pendiente de la próxima recarga; las pruebas locales y la
|
|
110
|
+
prueba de forma real están en verde. El registro real tampoco tiene todavía un `trusted root` para
|
|
111
|
+
`plugins-dhs`, de modo que una llamada real sigue fallando en cerrado a propósito.
|
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
# LifeCode RAG — Políticas y automatización
|
|
2
|
+
|
|
3
|
+
**Fecha:** 2026-11-17 · **Estado:** diseño propuesto (no implementado)
|
|
4
|
+
**Regla madre:** la automatización nunca concede lo que una persona no autorizó; el motor de políticas
|
|
5
|
+
puede denegar, nunca aprobar.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. Tres niveles
|
|
10
|
+
|
|
11
|
+
| Nivel | Quién decide | Ejemplos | Efecto si falta el permiso |
|
|
12
|
+
|---|---|---|---|
|
|
13
|
+
| **Automático** | Política vigente | recuperar, contar métricas, diagnosticar, exportar auditoría, indexar dentro de raíces ya autorizadas | se ejecuta o se omite; nunca pide |
|
|
14
|
+
| **Confirmación** | Persona, en el host o la UI | cambiar proveedor de embeddings, ampliar raíces, reindexado `all`, bajar retención de métricas | no se ejecuta; queda como propuesta |
|
|
15
|
+
| **Aprobación** | `ctx.approval.request` (solo `allowed-once`) | `forget`, acceso a rutas fuera de raíces, egress, purga masiva, operaciones destructivas | `approval-required` / `approval-unavailable` |
|
|
16
|
+
|
|
17
|
+
La desactivación de RAG no borra nada. La desinstalación no borra el almacén.
|
|
18
|
+
|
|
19
|
+
## 2. Qué es automático de verdad
|
|
20
|
+
|
|
21
|
+
### 2.1 Recuperación automática — límite real del host
|
|
22
|
+
|
|
23
|
+
**Corregido en PA6 (reconciliado 2026-11-18):** el host sí expone `agent/pre-step` y el plugin Project-Aware inyecta contexto con él (`lifecode-rag/index.js`, `lib/auto-context.mjs`). La v0.2 sigue sin inyectar porque su recuperación es de otro almacén. Texto original conservado por trazabilidad: no existía un punto de extensión verificado que permitiera **inyectar texto recuperado antes de
|
|
24
|
+
cada llamada al modelo**. `systemPrompt.section` añade instrucciones, no contenido por turno; escuchar
|
|
25
|
+
`system-prompt/assemble` está desaconsejado por la guía del host. Por tanto:
|
|
26
|
+
|
|
27
|
+
- **v0.2 no promete recuperación automática invisible.** Prometerla sin un hook sería mentir.
|
|
28
|
+
- Lo que sí se ofrece: una sección de prompt **opt-in** (`autoRetrieval.enabled=false` por defecto) que
|
|
29
|
+
instruye al agente a usar `lifecode_rag_search`/`lifecode_rag_context` cuando la pregunta toque
|
|
30
|
+
conocimiento del proyecto, con un presupuesto declarado.
|
|
31
|
+
- El agente sigue decidiendo la consulta; el motor no adivina.
|
|
32
|
+
|
|
33
|
+
Esta limitación se revisa en cada actualización del host; si aparece un hook (`agent.beforeModelCall` o
|
|
34
|
+
equivalente), se documenta y se evalúa con benchmark.
|
|
35
|
+
|
|
36
|
+
### 2.2 Indexación automática
|
|
37
|
+
|
|
38
|
+
Permitida solo dentro de `roots` ya autorizadas y con presupuesto:
|
|
39
|
+
|
|
40
|
+
```json
|
|
41
|
+
{
|
|
42
|
+
"version": 1,
|
|
43
|
+
"roots": ["C:/proyecto/docs"],
|
|
44
|
+
"autoIndex": { "enabled": false, "intervalMinutes": 15, "maxFilesPerRun": 50, "maxBytesPerRun": 10485760 },
|
|
45
|
+
"autoRetrieval": { "enabled": false, "budgetTokens": 1200, "maxChunks": 6 },
|
|
46
|
+
"retention": { "metricsDays": 90 },
|
|
47
|
+
"workspace": { "refreshSeconds": 30 }
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
- Se ejecuta **como mucho** cada `intervalMinutes`, y solo si no hay turno abierto (`agents.turnBoundaryOf`)
|
|
52
|
+
y hay sesión activa. Si el host no permite saberlo, **no indexa**: la duda no autoriza.
|
|
53
|
+
- Compara `(size, mtime)` y digest antes de leer: un fichero sin cambios no se re-extrae.
|
|
54
|
+
- Un fallo por fichero se registra y no aborta el lote; el lote termina con `{ingested, skipped, errors}`.
|
|
55
|
+
- Nunca amplía raíces: una ruta nueva fuera de `roots` exige confirmación y, si está fuera del proyecto,
|
|
56
|
+
aprobación por llamada como en la tool.
|
|
57
|
+
- Cancelación: `signal` del host o botón de la UI; se comprueba entre ficheros.
|
|
58
|
+
|
|
59
|
+
### 2.3 Diagnóstico y mantenimiento
|
|
60
|
+
|
|
61
|
+
- `doctor` y comprobación de integridad FTS: automáticos, solo lectura.
|
|
62
|
+
- `reindex fts`: automático si la integridad falla (reconstrucción derivada, no destruye datos).
|
|
63
|
+
- `reindex vectors`: confirmación; recorre todos los vectores y puede tardar.
|
|
64
|
+
- `forget`: siempre aprobación con alcance exacto (`sourceId`, URI, nº de chunks).
|
|
65
|
+
- Exportación de auditoría: automática (fichero derivado, regenerable).
|
|
66
|
+
|
|
67
|
+
## 3. Evaluador
|
|
68
|
+
|
|
69
|
+
```js
|
|
70
|
+
/**
|
|
71
|
+
* @returns {{decision:'allow'|'confirm'|'approve'|'deny', reason:string, code?:string, scope?:object}}
|
|
72
|
+
*/
|
|
73
|
+
evaluate(action, context)
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
`action` — `retrieve | ingest | reindex | forget | config.change | root.add | egress | purge`.
|
|
77
|
+
`context` = `{actor:'model'|'human'|'automation', sessionId, agentId, insideRoots, isProtected, egress, destructive}`.
|
|
78
|
+
|
|
79
|
+
### 3.1 Clasificación de purgas (única fuente; `OBSERVABILITY.md` §7 la referencia)
|
|
80
|
+
|
|
81
|
+
| Operación | Nivel | Alcance obligatorio | Nota |
|
|
82
|
+
|---|---|---|---|
|
|
83
|
+
| purga rutinaria > `metricsDays` | automático | `{kind:'retention'}` | dentro de la retención ya autorizada; solo métricas |
|
|
84
|
+
| bajar `metricsDays` | confirmación | `{from,to}` | no borra hasta confirmar |
|
|
85
|
+
| purga anticipada de métricas | confirmación | `{before}` | conserva lo que quede dentro de la nueva retención |
|
|
86
|
+
| purgar todo el histórico de métricas | aprobación | `{all:true}` | auditoría con recuento borrado |
|
|
87
|
+
| borrar el almacén | aprobación | `{store:true}` | exige copia previa verificable |
|
|
88
|
+
|
|
89
|
+
Una purga **nunca** toca `sources`, `chunks`, `vectors` ni la auditoría: esas filas no son telemetría.
|
|
90
|
+
|
|
91
|
+
### 3.2 Orden de evaluación (fail-closed)
|
|
92
|
+
|
|
93
|
+
1. ¿Ruta protegida (Skill Center, almacén propio)? — `deny` `path-denied`.
|
|
94
|
+
2. ¿Ruta fuera de raíces? — `approve` (una vez) o `deny` si no hay servicio de aprobación.
|
|
95
|
+
3. ¿Purga? — nivel de §3.1; `scope` obligatorio; sin `scope` es `deny`, no una aprobación genérica.
|
|
96
|
+
4. ¿Acción destructiva? — `approve` con `scope` obligatorio.
|
|
97
|
+
5. ¿Cambio de proveedor/raíz? — `confirm`.
|
|
98
|
+
6. ¿Dentro de política automática y presupuesto? — `allow`.
|
|
99
|
+
7. Cualquier duda — `deny`.
|
|
100
|
+
|
|
101
|
+
El evaluador **no** llama a `approval`; devuelve la decisión y el llamador (tool/ruta) pide la aprobación.
|
|
102
|
+
Así una ruta HTTP no puede aprobar por sí misma.
|
|
103
|
+
|
|
104
|
+
## 4. Integración con el host
|
|
105
|
+
|
|
106
|
+
- `ctx.approval.request({agent, toolName, reason, callId})`; solo `allowed-once` concede.
|
|
107
|
+
- Sin `approval` disponible —! `approval-unavailable` (fail-closed), nunca «seguir sin permiso».
|
|
108
|
+
- La UI muestra el estado «pendiente de aprobación»; no tiene botón de aprobar.
|
|
109
|
+
- Toda decisión (pedida/concedida/rechazada) se audita con `action`, `target`, `outcome`.
|
|
110
|
+
|
|
111
|
+
## 5. Auditoría de políticas
|
|
112
|
+
|
|
113
|
+
Cambiar `policies.json` es una escritura sensible:
|
|
114
|
+
|
|
115
|
+
- validación completa antes de escribir (desconocido —! `invalid-config`; nunca se ignora en silencio);
|
|
116
|
+
- escritura atómica (tmp + fsync + rename) y `updated_at`;
|
|
117
|
+
- evento `policy.change` en la cadena de auditoría con el diff de claves (no valores secretos);
|
|
118
|
+
- la configuración efectiva se puede leer por `GET /config`, sin secretos.
|
|
119
|
+
|
|
120
|
+
## 6. Presupuestos y degradación
|
|
121
|
+
|
|
122
|
+
- La indexación automática tiene techo por ejecución; al alcanzarlo para y reporta `truncated`.
|
|
123
|
+
- La recuperación automática tiene presupuesto de tokens; si no cabe, devuelve vacío con `truncated`
|
|
124
|
+
(nunca recorta un chunk a la mitad).
|
|
125
|
+
- Si el almacén está bloqueado (`store-busy`), la automatización reintenta una vez y desiste; no martillea.
|
|
126
|
+
- Si el proveedor de embeddings falla, la recuperación híbrida degrada a FTS y lo declara en `mode`.
|
|
127
|
+
|
|
128
|
+
## 7. Matriz de pruebas
|
|
129
|
+
|
|
130
|
+
| Caso | Esperado |
|
|
131
|
+
|---|---|
|
|
132
|
+
| Ruta con segmento `lifecode-skill-center` | `path-denied`, sin abrir almacén |
|
|
133
|
+
| Ruta fuera de raíz sin aprobación | `approval-required`, sin escritura |
|
|
134
|
+
| `forget` sin `scope` | error de validación, no aprobación genérica |
|
|
135
|
+
| `reindex all` sin confirmación | `confirm` (no ejecuta) |
|
|
136
|
+
| Automatización con presupuesto agotado | `truncated:true`, sin excepción |
|
|
137
|
+
| `approval` ausente | `approval-unavailable` |
|
|
138
|
+
| Cambio de config con clave desconocida | `invalid-config`, fichero intacto |
|
|
139
|
+
| Política con `roots` que incluye Skill Center | rechazo al guardar, no al usar |
|
|
140
|
+
| Purga rutinaria dentro de retención | `allow`, solo `metrics_daily` |
|
|
141
|
+
| Bajar `metricsDays` | `confirm`, sin borrar hasta confirmación |
|
|
142
|
+
| Purga total de métricas sin `scope` | `deny`, sin borrado |
|
|
143
|
+
| Borrar almacén | `approve` + copia previa; sin copia, `deny` |
|
|
144
|
+
| Purga con `sources` en el alcance | `deny` (no es telemetría) |
|
|
145
|
+
|
|
146
|
+
## 8. Sincronización periódica (M6.7)
|
|
147
|
+
|
|
148
|
+
El programador de `lib/sync-scheduler.mjs` sustituye a la automatización v0.2 sólo cuando el perfil
|
|
149
|
+
tiene registro Project-Aware. Se apoya **exclusivamente** en `ctx.timer.interval` del host.
|
|
150
|
+
|
|
151
|
+
### 8.1 Interruptor
|
|
152
|
+
|
|
153
|
+
- `automation.enabled` se lee al arrancar el programador y en cada tick, desde
|
|
154
|
+
`<profileRoot>/config.json`.
|
|
155
|
+
- Cambiar el fichero con el plugin ya cargado **no arranca ni detiene** el temporizador: hay que
|
|
156
|
+
recargar el plugin (`plugin_manager` con `enabled:false` y luego `true`) para que `apply` vuelva a
|
|
157
|
+
ejecutarse. Es el procedimiento de activación y desactivación soportado.
|
|
158
|
+
- Al descargar el plugin, el `ctx.effect` ejecuta `stop()`: cierra el disposer del temporizador y
|
|
159
|
+
aborta la pasada en curso por el `AbortSignal` propio del programador.
|
|
160
|
+
|
|
161
|
+
### 8.2 Presupuesto y degradación
|
|
162
|
+
|
|
163
|
+
| Situación | Respuesta |
|
|
164
|
+
|---|---|
|
|
165
|
+
| Presupuesto del tick agotado | corte entre ficheros, `stop_reason='budget'`, `outcome='partial'` |
|
|
166
|
+
| Límite de ficheros alcanzado | `stop_reason='file-limit'`, resto para la pasada siguiente |
|
|
167
|
+
| Tick solapado | no se ejecuta; `skippedTicks+1`, `lastSkipReason='already-running'` |
|
|
168
|
+
| Fallo de una pasada | `consecutiveFailures`, backoff `2^(n-1)` hasta 8 intervalos |
|
|
169
|
+
| Sin registro en el perfil | `{skipped:true, reason:'no-registry'}`, sin ruido por tick |
|
|
170
|
+
| Sin temporizador del host | `start()` devuelve `no-timer`; no hay respaldo global |
|
|
171
|
+
|
|
172
|
+
Un fallo no detiene el host ni desactiva el programador: se cuenta, se audita y se reintenta con
|
|
173
|
+
backoff. El reintento nunca repite efectos destructivos inciertos (el ledger y `effect_key` siguen
|
|
174
|
+
mandando).
|
|
175
|
+
|
|
176
|
+
### 8.3 Aprobaciones
|
|
177
|
+
|
|
178
|
+
La sincronización periódica no pide aprobación por fichero: trabaja dentro de raíces ya autorizadas y
|
|
179
|
+
su compuerta es la autorización por ámbito (`assertScopeSyncable`) y la revocación entre ficheros. La
|
|
180
|
+
egreso sigue cerrado: sin proveedor remoto, o `egress-denied`. Ninguna ejecución automática ejecuta
|
|
181
|
+
`forget`, `reindex` ni `ingest` con rutas fuera de raíz.
|
|
182
|
+
|
|
183
|
+
## 9. M6.8 — medición del presupuesto y observabilidad del backoff
|
|
184
|
+
|
|
185
|
+
Dos ajustes operativos salidos de M6.8. No cambian el contrato ni la política: cambian cómo se mide el
|
|
186
|
+
tiempo y qué se puede ver del scheduler.
|
|
187
|
+
|
|
188
|
+
### 9.1 El presupuesto se mide con reloj monotónico
|
|
189
|
+
|
|
190
|
+
`automation.tickBudgetMs` se compara ahora contra `performance.now()` (reloj monotónico de
|
|
191
|
+
`node:perf_hooks`), no contra `Date.now()`. Motivo: un ajuste de hora (NTP, cambio de zona, suspensión
|
|
192
|
+
del equipo) podía alargar un tick sin límite —si el reloj retrocede, la condición de fin no se cumple— o
|
|
193
|
+
cortarlo antes de tiempo.
|
|
194
|
+
|
|
195
|
+
- El corte sigue ocurriendo **entre ficheros**, en dos puntos: antes de abrir el lote de pendientes y
|
|
196
|
+
dentro de `authorize`, que corre antes de preparar y escribir cada fichero. Nunca dentro de una
|
|
197
|
+
transacción.
|
|
198
|
+
- El reloj de pared se usa **solo** para marcas persistidas (`operation_steps`, `sync_state`, auditoría)
|
|
199
|
+
y para el campo informativo `ms`.
|
|
200
|
+
- `syncScope`/`syncScopes` aceptan `monotonic` como dependencia opcional para pruebas; el scheduler lo
|
|
201
|
+
propaga.
|
|
202
|
+
|
|
203
|
+
### 9.2 El backoff se puede observar
|
|
204
|
+
|
|
205
|
+
`status()` expone ahora, además de lo anterior:
|
|
206
|
+
|
|
207
|
+
| Campo | Significado |
|
|
208
|
+
|---|---|
|
|
209
|
+
| `consecutiveFailures` | Fallos consecutivos del tick (no de un fichero) |
|
|
210
|
+
| `lastError` | Último error (`code`, mensaje), o `null` |
|
|
211
|
+
| `nextAttemptAt` | Instante del próximo intento tras un fallo, o `null` |
|
|
212
|
+
| `backoffFactor` | `min(2**(n-1), 8)`; `0` sin fallos |
|
|
213
|
+
| `backoffRemainingMs` | Milisegundos que faltan hasta `nextAttemptAt` |
|
|
214
|
+
| `skippedTicks` / `lastSkipReason` | Ticks omitidos y por qué (`already-running`, `backoff`, `disabled`) |
|
|
215
|
+
| `effective` | Política aplicada: intervalo, ficheros por pasada y presupuesto |
|
|
216
|
+
|
|
217
|
+
Fórmula: `nextAttemptAt = lastAttemptAt + intervalMs * min(2**(n-1), 8)`. El primer fallo ya espera ×2:
|
|
218
|
+
no hay reintento inmediato. Un fallo **de fichero** no es un fallo **de tick** y no activa backoff.
|
|
219
|
+
|
|
220
|
+
### 9.3 Desactivar surte efecto inmediato
|
|
221
|
+
|
|
222
|
+
Si `automation.enabled` pasa a `false` durante un backoff, el siguiente tick lo detecta antes de
|
|
223
|
+
comprobar la espera, la cancela y resetea contador y `nextAttemptAt`. `stop()` hace lo mismo. No queda
|
|
224
|
+
una espera preparada para el siguiente arranque.
|
|
225
|
+
|
|
226
|
+
### 9.4 Límites declarados
|
|
227
|
+
|
|
228
|
+
- El backoff y el corte por presupuesto están probados de forma determinista con reloj y temporizador
|
|
229
|
+
inyectados, pero **no** se han provocado en el host real: exigía romper la configuración del perfil o
|
|
230
|
+
un árbol artificial dentro de la raíz autorizada.
|
|
231
|
+
- El scheduler sigue siendo de una sola instancia por proceso; no hay lease entre host y CLI (ver
|
|
232
|
+
`RISK-REGISTER.md`, R-02).
|