@designerbyron/lifecode-rag 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +220 -2
  3. package/bin/lifecode-rag.mjs +449 -0
  4. package/client.js +3515 -0
  5. package/cordis.patch.yml +3 -0
  6. package/docs/ARCHITECTURE-v0.2.md +269 -0
  7. package/docs/AUTO-DISCOVERY.md +111 -0
  8. package/docs/AUTOMATION-POLICIES.md +232 -0
  9. package/docs/CONTRATO-v0.1.md +195 -0
  10. package/docs/EMBEDDING-PROVIDERS.md +105 -0
  11. package/docs/OBSERVABILITY.md +241 -0
  12. package/docs/PA-UI-0-API-CONTRACT.md +887 -0
  13. package/docs/PERFORMANCE-BUDGETS.md +118 -0
  14. package/docs/PROJECT-AWARE-ARCHITECTURE.md +580 -0
  15. package/docs/PROJECT-AWARE-DATA-CONTRACT.md +411 -0
  16. package/docs/PROJECT-AWARE-ERROR-CONTRACT.md +112 -0
  17. package/docs/PROJECT-AWARE-SESSION-CONTRACT.md +120 -0
  18. package/docs/WORKSPACE-API.md +239 -0
  19. package/icon.svg +7 -0
  20. package/index.js +198 -0
  21. package/lib/audit-export.mjs +70 -0
  22. package/lib/audit.mjs +120 -0
  23. package/lib/auto-context.mjs +322 -0
  24. package/lib/automation.mjs +214 -0
  25. package/lib/chunk.mjs +100 -0
  26. package/lib/config-resolve.mjs +119 -0
  27. package/lib/context.mjs +150 -0
  28. package/lib/conversation-events.mjs +145 -0
  29. package/lib/db.mjs +309 -0
  30. package/lib/diagnose.mjs +197 -0
  31. package/lib/discovery.mjs +402 -0
  32. package/lib/doctor.mjs +82 -0
  33. package/lib/embed.mjs +96 -0
  34. package/lib/embedders.mjs +103 -0
  35. package/lib/errors.mjs +231 -0
  36. package/lib/exec-context.mjs +238 -0
  37. package/lib/extract.mjs +260 -0
  38. package/lib/harness-workspaces.mjs +85 -0
  39. package/lib/hash.mjs +34 -0
  40. package/lib/ingest.mjs +239 -0
  41. package/lib/inputs.mjs +67 -0
  42. package/lib/library-state.mjs +252 -0
  43. package/lib/maintenance.mjs +113 -0
  44. package/lib/metrics.mjs +164 -0
  45. package/lib/migrate.mjs +373 -0
  46. package/lib/operations.mjs +132 -0
  47. package/lib/pa-api.mjs +946 -0
  48. package/lib/paths.mjs +345 -0
  49. package/lib/policy.mjs +125 -0
  50. package/lib/profile.mjs +128 -0
  51. package/lib/readmodel.mjs +159 -0
  52. package/lib/recovery.mjs +557 -0
  53. package/lib/registry-schema.mjs +206 -0
  54. package/lib/registry.mjs +606 -0
  55. package/lib/resolve.mjs +318 -0
  56. package/lib/retention.mjs +143 -0
  57. package/lib/revocation.mjs +124 -0
  58. package/lib/roots-structure.mjs +224 -0
  59. package/lib/schema.mjs +173 -0
  60. package/lib/scope-ops.mjs +379 -0
  61. package/lib/scope-stores.mjs +128 -0
  62. package/lib/search.mjs +345 -0
  63. package/lib/selection.mjs +225 -0
  64. package/lib/server.mjs +340 -0
  65. package/lib/session-identity.mjs +51 -0
  66. package/lib/sessions.mjs +343 -0
  67. package/lib/sync-scheduler.mjs +354 -0
  68. package/lib/sync.mjs +755 -0
  69. package/lib/tags.mjs +45 -0
  70. package/lib/tools.mjs +364 -0
  71. package/lib/trusted-roots.mjs +149 -0
  72. package/lib/worker-context.mjs +22 -0
  73. package/package.json +67 -5
@@ -0,0 +1,411 @@
1
+ # Contrato de datos — Project-Aware RAG (PA0)
2
+
3
+ **Estado:** especificación documental. **No ejecutada.** Ninguna base de datos se creó ni se migró.
4
+ **Base:** LifeCode RAG v0.2.0 (esquema v3 por almacén único).
5
+ **Ámbito:** PA0. La implementación corresponde a PA1 (registro y migración) y PA3 (almacenes por ámbito).
6
+
7
+ Este documento fija el **modelo de datos normativo**: el SQL del registro por perfil, el contrato de
8
+ metadatos de cada almacén de ámbito y las reglas de identidad, rutas e integridad. El SQL es especificación:
9
+ se revisa aquí, se implementa en PA1.
10
+
11
+ ## 1. Principios
12
+
13
+ 1. **Un registro por perfil.** Cada perfil de DeepSeek Harness tiene su `registry.sqlite3`; ningún registro
14
+ descubre ni abre almacenes de otro perfil.
15
+ 2. **Un almacén por ámbito.** Proyecto y biblioteca tienen almacenes separados. El aislamiento se puede
16
+ verificar abriendo únicamente los ficheros permitidos; no depende de un `WHERE project_id = ?`.
17
+ 3. **Identidad lógica, no derivada.** `project_id` y `library_id` son ULID con prefijo, nunca el nombre ni
18
+ la ruta.
19
+ 4. **Integridad declarada.** Todo almacén declara qué ámbito es y a qué perfil pertenece; si no coincide con
20
+ el registro, se falla en cerrado.
21
+ 5. **Sin borrado por desaparición.** `missing` es un estado observado, no una orden de borrado.
22
+
23
+ ## 2. Ubicación: contrato abstracto, no ruta inventada
24
+
25
+ PA0 **no fija una ruta física** porque no se ha verificado una API del host que la determine sin modificar el
26
+ entorno. El contrato es:
27
+
28
+ ```
29
+ profile_data_root(profile) → raíz de datos del perfil (resuelta por el host)
30
+ registry_path(profile) = <profile_data_root>/lifecode-rag/registry.sqlite3
31
+ scope_path(profile, kind, id) = <profile_data_root>/lifecode-rag/scopes/<kind>_<id>/rag.sqlite3
32
+ ```
33
+
34
+ - `kind` ∈ `prj | lib`; `<kind>_<id>` usa el identificador completo con prefijo (`prj_01J…`).
35
+ - `LIFECODE_RAG_ROOT` (v0.2) se conserva como **override explícito de desarrollo**; si está definido, el
36
+ registro y los ámbitos cuelgan de él y el perfil queda registrado en `meta.profile_id` para impedir
37
+ mezclas.
38
+ - **Pendiente PA1:** verificar cómo expone el host la raíz de datos por perfil (`DSH_PROFILE_DIR`,
39
+ `storageDomain` u otro servicio) y si escribir ahí es admisible. Hasta entonces, la resolución es un
40
+ contrato, no una afirmación.
41
+
42
+ Comportamiento ante perfil cambiado, eliminado o inaccesible: `registry-unavailable`; el registro no intenta
43
+ "adivinar" otro perfil.
44
+
45
+ ## 3. SQL del registro (normativo)
46
+
47
+ **Decisión cerrada O-PA0-1 (2026-11-17):** una única tabla `roots`. Se elige sobre dos tablas
48
+ (`project_roots` + `library_roots`) porque la FK de `sync_state.root_id` no puede apuntar a dos tablas y
49
+ porque una sola fila por raíz impide por construcción un `root_id` cruzado. La pertenencia a proyecto o
50
+ biblioteca se valida con disparadores, no con FK (SQLite no tiene FK polimórfica); el precio es explícito y
51
+ está cubierto por pruebas en PA1.
52
+
53
+ ```sql
54
+ PRAGMA application_id = 1279480402; -- 'LCRR' (registro Project-Aware); el almacén de ámbito conserva 'LCRG'
55
+ PRAGMA user_version = 2; -- v2 (ACP-01): añade pa_selection. Migración aditiva desde v1.
56
+ PRAGMA journal_mode = WAL;
57
+ PRAGMA foreign_keys = ON;
58
+
59
+ CREATE TABLE meta (
60
+ key TEXT PRIMARY KEY,
61
+ value TEXT NOT NULL
62
+ ) STRICT;
63
+
64
+ -- Una fila por perfil; profile_id es el identificador estable del perfil del host.
65
+ INSERT INTO meta(key, value) VALUES
66
+ ('registry_version', '1'),
67
+ ('profile_id', :profile_id),
68
+ ('created_at', :now);
69
+
70
+ CREATE TABLE projects (
71
+ id TEXT PRIMARY KEY
72
+ CHECK (substr(id, 1, 4) = 'prj_' AND length(id) = 30
73
+ AND substr(id, 5) NOT GLOB '*[^0-9A-HJKMNP-TV-Z]*'),
74
+ name TEXT NOT NULL CHECK (length(trim(name)) BETWEEN 1 AND 120),
75
+ status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','archived')),
76
+ created_at TEXT NOT NULL,
77
+ updated_at TEXT NOT NULL,
78
+ archived_at TEXT,
79
+ CHECK ((status = 'archived') = (archived_at IS NOT NULL))
80
+ ) STRICT;
81
+
82
+ CREATE TABLE libraries (
83
+ id TEXT PRIMARY KEY
84
+ CHECK (substr(id, 1, 4) = 'lib_' AND length(id) = 30
85
+ AND substr(id, 5) NOT GLOB '*[^0-9A-HJKMNP-TV-Z]*'),
86
+ name TEXT NOT NULL CHECK (length(trim(name)) BETWEEN 1 AND 120),
87
+ status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','archived')),
88
+ created_at TEXT NOT NULL,
89
+ updated_at TEXT NOT NULL,
90
+ archived_at TEXT,
91
+ CHECK ((status = 'archived') = (archived_at IS NOT NULL))
92
+ ) STRICT;
93
+
94
+ -- Una raíz pertenece a UN ámbito. `scope_kind`/`scope_id` son la identidad del ámbito; el prefijo debe
95
+ -- coincidir con el tipo (CHECK). La existencia del ámbito la garantizan los disparadores de §3.1.
96
+ CREATE TABLE roots (
97
+ id TEXT PRIMARY KEY
98
+ CHECK (substr(id, 1, 3) = 'rt_' AND length(id) = 29
99
+ AND substr(id, 4) NOT GLOB '*[^0-9A-HJKMNP-TV-Z]*'),
100
+ scope_kind TEXT NOT NULL CHECK (scope_kind IN ('prj','lib')),
101
+ scope_id TEXT NOT NULL,
102
+ path TEXT NOT NULL CHECK (length(path) > 0),
103
+ path_key TEXT NOT NULL UNIQUE, -- ruta canónica; minúsculas en Windows; única en TODO el registro
104
+ state TEXT NOT NULL DEFAULT 'authorized' CHECK (state IN ('authorized','revoked')),
105
+ added_at TEXT NOT NULL,
106
+ added_by TEXT NOT NULL CHECK (added_by IN ('human','host')),
107
+ revoked_at TEXT,
108
+ CHECK ((state = 'revoked') = (revoked_at IS NOT NULL)),
109
+ CHECK ((scope_kind = 'prj' AND substr(scope_id, 1, 4) = 'prj_')
110
+ OR (scope_kind = 'lib' AND substr(scope_id, 1, 4) = 'lib_')),
111
+ -- Clave candidata para que `sync_state` pueda referenciar la raíz CON su ámbito. Sin ella, una FK
112
+ -- compuesta no podría demostrar que el ámbito de `sync_state` es el de su raíz.
113
+ UNIQUE (id, scope_kind, scope_id)
114
+ ) STRICT;
115
+
116
+ CREATE TRIGGER roots_scope_insert
117
+ BEFORE INSERT ON roots
118
+ WHEN (NEW.scope_kind = 'prj' AND NOT EXISTS (SELECT 1 FROM projects WHERE id = NEW.scope_id))
119
+ OR (NEW.scope_kind = 'lib' AND NOT EXISTS (SELECT 1 FROM libraries WHERE id = NEW.scope_id))
120
+ BEGIN
121
+ SELECT RAISE(ABORT, 'root-scope-missing');
122
+ END;
123
+
124
+ -- El ámbito de una raíz no se reasigna: se revoca y se crea otra.
125
+ CREATE TRIGGER roots_scope_immutable
126
+ BEFORE UPDATE OF scope_kind, scope_id ON roots
127
+ BEGIN
128
+ SELECT RAISE(ABORT, 'root-scope-immutable');
129
+ END;
130
+
131
+ -- Borrar un ámbito con raíces dejaría raíces huérfanas y `sync_state` colgado. El borrado de ámbitos no
132
+ -- forma parte de PA0; si se define, exigirá una operación coordinada con auditoría. Mientras tanto, se
133
+ -- prohíbe en la base, no solo en la aplicación.
134
+ CREATE TRIGGER projects_roots_guard
135
+ BEFORE DELETE ON projects
136
+ WHEN EXISTS (SELECT 1 FROM roots WHERE scope_kind = 'prj' AND scope_id = OLD.id)
137
+ BEGIN
138
+ SELECT RAISE(ABORT, 'scope-has-roots');
139
+ END;
140
+
141
+ CREATE TRIGGER libraries_roots_guard
142
+ BEFORE DELETE ON libraries
143
+ WHEN EXISTS (SELECT 1 FROM roots WHERE scope_kind = 'lib' AND scope_id = OLD.id)
144
+ BEGIN
145
+ SELECT RAISE(ABORT, 'scope-has-roots');
146
+ END;
147
+
148
+ -- Un grant es directo proyecto → biblioteca. No hay herencia ni anidamiento.
149
+ CREATE TABLE grants (
150
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
151
+ project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
152
+ library_id TEXT NOT NULL REFERENCES libraries(id) ON DELETE CASCADE,
153
+ permission TEXT NOT NULL DEFAULT 'read' CHECK (permission = 'read'),
154
+ granted_at TEXT NOT NULL,
155
+ granted_by TEXT NOT NULL CHECK (granted_by IN ('human','host')),
156
+ revoked_at TEXT,
157
+ revoked_by TEXT,
158
+ CHECK ((revoked_at IS NULL) = (revoked_by IS NULL))
159
+ ) STRICT;
160
+
161
+ CREATE UNIQUE INDEX grants_one_open
162
+ ON grants(project_id, library_id)
163
+ WHERE revoked_at IS NULL;
164
+
165
+ CREATE TABLE session_scope (
166
+ session_id TEXT PRIMARY KEY
167
+ CHECK (length(session_id) BETWEEN 1 AND 200 AND session_id NOT GLOB '*[^ -~]*'),
168
+ project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE RESTRICT,
169
+ state TEXT NOT NULL DEFAULT 'active'
170
+ CHECK (state IN ('active','expired','invalidated')),
171
+ selection_source TEXT NOT NULL CHECK (selection_source IN ('explicit','cwd')),
172
+ selected_by TEXT NOT NULL CHECK (selected_by IN ('human','host')),
173
+ selected_at TEXT NOT NULL,
174
+ updated_at TEXT NOT NULL,
175
+ expires_at TEXT,
176
+ invalidated_at TEXT,
177
+ invalid_reason TEXT CHECK (invalid_reason IS NULL OR invalid_reason IN
178
+ ('project-archived','grant-revoked','root-revoked','profile-changed',
179
+ 'admin','session-cloned')),
180
+ cwd TEXT,
181
+ clone_of TEXT,
182
+ revision INTEGER NOT NULL DEFAULT 1 CHECK (revision >= 1),
183
+ CHECK (state <> 'active' OR (invalidated_at IS NULL AND invalid_reason IS NULL)),
184
+ CHECK (state <> 'expired' OR (expires_at IS NOT NULL AND invalidated_at IS NULL
185
+ AND invalid_reason IS NULL)),
186
+ CHECK (state <> 'invalidated' OR (invalidated_at IS NOT NULL AND invalid_reason IS NOT NULL
187
+ AND expires_at IS NULL))
188
+ ) STRICT;
189
+
190
+ -- Estado de sincronización por raíz y fuente; sirve para missing/unreadable sin borrar.
191
+ -- La FK es COMPUESTA: el ámbito de `sync_state` debe ser exactamente el de su raíz. Una raíz de proyecto
192
+ -- no puede tener filas de sincronización de biblioteca, ni al revés, aunque el `root_id` exista.
193
+ CREATE TABLE sync_state (
194
+ scope_kind TEXT NOT NULL CHECK (scope_kind IN ('prj','lib')),
195
+ scope_id TEXT NOT NULL,
196
+ root_id TEXT NOT NULL,
197
+ source_key TEXT NOT NULL, -- uri relativa o clave estable dentro de la raíz
198
+ status TEXT NOT NULL CHECK (status IN ('present','missing','unreadable')),
199
+ last_seen_at TEXT,
200
+ last_hash TEXT,
201
+ missing_since TEXT,
202
+ error_code TEXT,
203
+ updated_at TEXT NOT NULL,
204
+ PRIMARY KEY (scope_kind, scope_id, root_id, source_key),
205
+ CHECK ((scope_kind = 'prj' AND substr(scope_id, 1, 4) = 'prj_')
206
+ OR (scope_kind = 'lib' AND substr(scope_id, 1, 4) = 'lib_')),
207
+ FOREIGN KEY (root_id, scope_kind, scope_id)
208
+ REFERENCES roots(id, scope_kind, scope_id) ON DELETE CASCADE
209
+ ) STRICT;
210
+
211
+ CREATE TABLE audit_registry (
212
+ seq INTEGER PRIMARY KEY AUTOINCREMENT,
213
+ at TEXT NOT NULL,
214
+ actor TEXT NOT NULL CHECK (actor IN ('human','host','model','automation')),
215
+ session_id TEXT,
216
+ action TEXT NOT NULL,
217
+ target TEXT NOT NULL,
218
+ outcome TEXT NOT NULL CHECK (outcome IN ('ok','failed','denied','skipped')),
219
+ detail TEXT,
220
+ prev_hash TEXT NOT NULL,
221
+ hash TEXT NOT NULL
222
+ ) STRICT;
223
+
224
+ CREATE TABLE operations (
225
+ id TEXT PRIMARY KEY
226
+ CHECK (substr(id, 1, 3) = 'op_' AND length(id) = 29
227
+ AND substr(id, 4) NOT GLOB '*[^0-9A-HJKMNP-TV-Z]*'),
228
+ kind TEXT NOT NULL, -- grant, revoke, migrate, archive, delete-scope
229
+ state TEXT NOT NULL CHECK (state IN ('started','committed','failed','reconciled')),
230
+ started_at TEXT NOT NULL,
231
+ finished_at TEXT,
232
+ detail TEXT,
233
+ CHECK ((state IN ('committed','failed','reconciled')) = (finished_at IS NOT NULL))
234
+ ) STRICT;
235
+
236
+ CREATE TABLE operation_steps (
237
+ operation_id TEXT NOT NULL REFERENCES operations(id) ON DELETE CASCADE,
238
+ step TEXT NOT NULL,
239
+ state TEXT NOT NULL CHECK (state IN ('pending','done','failed')),
240
+ effect_key TEXT, -- clave idempotente del efecto ya aplicado
241
+ updated_at TEXT NOT NULL,
242
+ PRIMARY KEY (operation_id, step)
243
+ ) STRICT;
244
+
245
+ -- Un `effect_key` no se repite dentro de la misma operación: si ya está registrado, el efecto se aplicó.
246
+ CREATE UNIQUE INDEX operation_steps_effect
247
+ ON operation_steps(operation_id, effect_key)
248
+ WHERE effect_key IS NOT NULL;
249
+
250
+ -- v2 · Selección de proyecto del panel (CR-1). Una fila por perfil, con revisión monotónica para el
251
+ -- compare-and-swap. No es identidad: `principal` sólo registra el principal del host que la confirmó.
252
+ CREATE TABLE pa_selection (
253
+ selection_key TEXT PRIMARY KEY CHECK (selection_key='profile'),
254
+ project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
255
+ revision INTEGER NOT NULL CHECK (revision >= 1),
256
+ selection_source TEXT NOT NULL CHECK (selection_source IN ('explicit','cwd')),
257
+ selected_by TEXT NOT NULL CHECK (selected_by IN ('human','host')),
258
+ principal TEXT NOT NULL DEFAULT 'owner',
259
+ selected_at TEXT NOT NULL,
260
+ updated_at TEXT NOT NULL
261
+ ) STRICT;
262
+
263
+ CREATE INDEX projects_status ON projects(status);
264
+ CREATE INDEX roots_scope ON roots(scope_kind, scope_id, state);
265
+ CREATE INDEX grants_project_open ON grants(project_id) WHERE revoked_at IS NULL;
266
+ CREATE INDEX session_scope_project ON session_scope(project_id, state);
267
+ CREATE INDEX session_scope_expiry ON session_scope(state, expires_at);
268
+ CREATE INDEX pa_selection_project ON pa_selection(project_id);
269
+ CREATE INDEX sync_state_status ON sync_state(scope_kind, scope_id, status);
270
+ CREATE INDEX audit_registry_at ON audit_registry(at);
271
+ ```
272
+
273
+ ### 3.1 Por qué la pertenencia se valida con disparadores
274
+
275
+ `roots.scope_id` apunta a `projects` **o** a `libraries` según `scope_kind`. SQLite no admite una FK
276
+ polimórfica, así que el modelo hace lo siguiente, y nada más:
277
+
278
+ - `CHECK` de prefijo: `prj_` ↔ `scope_kind='prj'`, `lib_` ↔ `scope_kind='lib'` (impide la asociación
279
+ incompatible evidente).
280
+ - Disparador de inserción: aborta si el `scope_id` no existe en la tabla que indica `scope_kind`
281
+ (`root-scope-missing`). Esto convierte la pertenencia en una invariante real, no en una convención.
282
+ - Disparador de actualización: prohíbe reasignar una raíz a otro ámbito (`root-scope-immutable`); se revoca y
283
+ se crea otra.
284
+ - `DELETE` de proyecto/biblioteca con raíces: **protegido por disparador** (`scope-has-roots`), no solo por la
285
+ aplicación. El borrado de ámbitos **no forma parte de PA0**; si se define, exigirá código de error propio,
286
+ operación coordinada y auditoría.
287
+ - `sync_state`: la FK compuesta `(root_id, scope_kind, scope_id) → roots(id, scope_kind, scope_id)` demuestra
288
+ que el ámbito de la fila es el de su raíz. No hay `CHECK` con subconsulta: SQLite no garantiza el orden de
289
+ evaluación de `CHECK` frente a la FK, y la FK ya cubre la existencia.
290
+
291
+ Pruebas obligatorias en PA1: insertar raíz con `scope_kind='prj'` y `scope_id` de biblioteca → falla;
292
+ insertar raíz con `scope_id` inexistente → falla; actualizar `scope_id` → falla; insertar dos raíces con el
293
+ mismo `path_key` → falla; insertar `sync_state` con `root_id` de otro ámbito → falla; borrar proyecto con
294
+ raíces → falla (`scope-has-roots`); insertar raíz válida → pasa.
295
+
296
+ ### 3.2 Identificadores: qué valida SQLite y qué no
297
+
298
+ | Identificador | Forma | Lo que valida el `CHECK` | Lo que **no** valida |
299
+ |---|---|---|---|
300
+ | `projects.id` | `prj_` + 26 ULID = 30 | prefijo, longitud exacta, alfabeto Crockford (`0-9A-HJKMNP-TV-Z`), sin `I/L/O/U` | que sea un ULID real (timestamp + aleatoriedad), monotonicidad, unicidad global (la da la PK) |
301
+ | `libraries.id` | `lib_` + 26 = 30 | ídem | ídem |
302
+ | `roots.id` | `rt_` + 26 = 29 | ídem | ídem |
303
+ | `operations.id` | `op_` + 26 = 29 | ídem | ídem |
304
+ | `session_scope.session_id` | cadena del host | longitud 1–200 y ASCII imprimible | que sea un ID de sesión vivo del host (lo verifica la resolución en PA2) |
305
+
306
+ El `CHECK` **no** demuestra que el ULID sea válido: sólo demuestra forma. La aplicación (PA1) debe además
307
+ decodificar el ULID y rechazar los que no lo sean; se documenta como validación de aplicación, no de esquema.
308
+ Pruebas: carácter fuera del alfabeto (`I`, `L`, `O`, `U`, `-`), longitud 29/31, prefijo equivocado, minúsculas;
309
+ cada caso debe fallar en inserción directa.
310
+
311
+ **Unicidad global de identidad:** `projects.id`, `libraries.id`, `roots.id`, `operations.id` son PK; no hay
312
+ dos filas con el mismo identificador. **Unicidad global de ruta:** `roots.path_key` es `UNIQUE` para todas
313
+ las filas (incluidas revocadas). Reactivar una ruta revocada se hace actualizando esa fila (`state`,
314
+ `revoked_at = NULL`), no insertando otra.
315
+
316
+ Reglas adicionales:
317
+
318
+ - Una misma ruta física no puede pertenecer a dos proyectos ni a un proyecto y una biblioteca: lo impide
319
+ `path_key UNIQUE`.
320
+ - Raíces solapadas dentro del mismo ámbito (una contenida en otra) se rechazan con `root-overlap`; el registro
321
+ no intenta deducir la intención.
322
+ - `libraries` nunca referencia `projects`; `projects` solo se relaciona con `libraries` mediante `grants`.
323
+ - No hay `parent_library_id` ni `parent_project_id`: el anidamiento es imposible por esquema.
324
+
325
+ ## 4. Contrato de metadatos de cada almacén de ámbito
326
+
327
+ Cada `rag.sqlite3` de ámbito conserva el esquema v3 de v0.2 y añade estas claves obligatorias en `meta`:
328
+
329
+ | Clave | Valor | Regla |
330
+ |---|---|---|
331
+ | `scope_id` | `prj_…` o `lib_…` | Debe coincidir con el directorio y con el registro; si no, `scope-store-corrupt` |
332
+ | `scope_kind` | `project` \| `library` | Coherente con el prefijo |
333
+ | `profile_id` | el del registro | Distinto → `scope-forbidden` (no se abre) |
334
+ | `schema_version` | entero | Mayor que el soportado → `scope-store-corrupt` (fail closed) |
335
+ | `migration_version` | entero | Trazabilidad de migraciones |
336
+ | `store_state` | `ready` \| `migrating` \| `corrupt` | `migrating`/`corrupt` → no se consulta |
337
+ | `created_at` | ISO-8601 | — |
338
+
339
+ El registro guarda, por ámbito, la ruta esperada del almacén para poder detectar un `scope_id` que apunta a
340
+ otro sitio. La comprobación es **previa a cualquier lectura de contenido**.
341
+
342
+ ## 5. Identidad y rutas
343
+
344
+ - ULID Crockford (26 caracteres, sin `I`, `L`, `O`, `U`), prefijo `prj_` / `lib_`; los IDs de raíz usan
345
+ `rt_` y los de operación `op_`. No se derivan del nombre ni de la ruta. El esquema valida forma; la
346
+ validez real del ULID la comprueba la aplicación (§3.2).
347
+ - Canonicalización: `realpathSync.native`, después plegado a minúsculas para `path_key` en Windows; se
348
+ conserva la forma original en `path` para mostrarla.
349
+ - Se rechazan symlinks, junctions y reparse points en raíces y ficheros; los hardlinks de fichero se
350
+ rechazan con `hardlink-refused` (regla heredada de v0.1).
351
+ - Traversal: toda ruta relativa se resuelve contra la raíz autorizada y se comprueba que el resultado sigue
352
+ dentro; `..`, rutas absolutas y unidades distintas se rechazan.
353
+ - Dos raíces con el mismo `path_key` → `registry-corrupt` (no se elige una "ganadora").
354
+ - Archivar un proyecto no borra su almacén ni sus raíces; solo impide seleccionarlo.
355
+
356
+ ## 6. Integridad y recuperación
357
+
358
+ - `PRAGMA integrity_check` antes de confiar en un almacén; fallo → `registry-corrupt` o
359
+ `scope-store-corrupt` según el fichero.
360
+ - La auditoría encadenada se verifica por almacén; una cadena rota no se repara automáticamente: se marca
361
+ `corrupt` y se informa.
362
+ - Copia de seguridad previa a cualquier migración; el original se conserva (ver contrato de migración en la
363
+ arquitectura).
364
+ - El registro no se reconstruye "a ojo" desde los directorios: si falta, `registry-unavailable`; si existe
365
+ pero no cuadra, `registry-corrupt`.
366
+ - Las operaciones multicontenedor usan `operations` + `operation_steps`; una operación `started` al abrir el
367
+ registro es una **operación incompleta** y se reconcilia antes de aceptar nuevas (§3.3 del contrato de
368
+ arquitectura).
369
+
370
+ ### 6.1 Idempotencia y efectos ya aplicados
371
+
372
+ El problema real: un paso puede aplicar su efecto y el proceso caer antes de persistir `state='done'`. Al
373
+ reconciliar, no se puede saber por el `state` si el efecto ocurrió.
374
+
375
+ 1. **Clave de efecto única por operación.** `operation_steps(operation_id, effect_key)` es único (índice
376
+ parcial `WHERE effect_key IS NOT NULL`). Insertar el `effect_key` es el acto que registra el efecto; un
377
+ segundo intento con la misma clave falla por unicidad y se interpreta como "ya aplicado".
378
+ 2. **Comprobación previa de efecto, no de estado.** Antes de aplicar un paso, se comprueba el efecto en su
379
+ destino: ¿existe el grant?, ¿está la raíz revocada?, ¿coincide el hash del almacén? Si el efecto ya está,
380
+ se marca `done` sin repetirlo.
381
+ 3. **Pasos destructivos con resultado incierto no se repiten.** Si no se puede comprobar el efecto (fichero
382
+ ilegible, error de E/S), el paso pasa a `failed` y la operación a `failed`/`reconciled` con `detail`; nunca
383
+ se reintenta a ciegas un borrado o una migración.
384
+ 4. **Rollback repetible.** Cada paso de rollback lleva su propio `effect_key`; repetirlo es seguro por la
385
+ misma unicidad y comprobación previa.
386
+ 5. **Auditoría.** Cada transición (`pending → done`, `done → rollback`, `failed`) se audita con
387
+ `operations.id` y `step`, sin contenido de usuario.
388
+
389
+ `effect_key` es una cadena estable derivada del paso y su destino (por ejemplo `revoke:<grant_id>`), no un
390
+ timestamp: dos intentos distintos del mismo efecto deben producir la misma clave.
391
+
392
+ ## 7. Lo que este contrato NO afirma
393
+
394
+ - No afirma que la ruta por perfil esté verificada (pendiente PA1).
395
+ - No afirma que el esquema se haya creado o migrado.
396
+ - No afirma que los disparadores se hayan probado: son especificación; sus pruebas pertenecen a PA1.
397
+ - No afirma atomicidad entre registro y almacenes: las operaciones multicontenedor se documentan como
398
+ coordinadas, con estado parcial y reconciliación (`operations`).
399
+
400
+ ## 8. Registro de revisión ACP-01 (2026-11-21)
401
+
402
+ - **`user_version` 1 → 2.** Tabla nueva `pa_selection` (§3) e índice `pa_selection_project`. La migración
403
+ vive en `REGISTRY_MIGRATIONS` (`lib/registry-schema.mjs`) y la aplica `migrateRegistry` dentro de
404
+ `BEGIN IMMEDIATE` al abrir; es **aditiva**: no altera ni borra filas existentes, y un registro v1 sigue
405
+ sirviendo con sus proyectos, raíces, concesiones y cadena de auditoría intactos.
406
+ - **Prueba de la migración:** `tests/registry.test.mjs` («registro v1 se migra a v2…»): degrada un registro
407
+ a v1 (sin `pa_selection`, `user_version=1`), reabre, comprueba que la tabla existe, que la versión sube en
408
+ `PRAGMA user_version` y en `meta.registry_version`, que los proyectos siguen y que la cadena de auditoría
409
+ verifica; y que reabrir el registro ya migrado no vuelve a migrar.
410
+ - **Compatibilidad hacia atrás:** un build anterior (v1) que abra un registro v2 recibe
411
+ `store-version-unsupported`; por eso la migración va en el mismo acto que el despliegue del build nuevo.
@@ -0,0 +1,112 @@
1
+ # Contrato de errores — Project-Aware RAG (PA0)
2
+
3
+ **Estado:** implementado y verificado en PA1–PA4 (probado local). Actualizado en PA4 con la semántica
4
+ **fail-closed** de la revocación durante una operación y con los códigos de raíces, recuperación y
5
+ operaciones interrumpidas.
6
+ **Regla transversal:** un error de seguridad, permisos o integridad **nunca** se convierte en un resultado
7
+ vacío aparentemente exitoso. Si no se puede demostrar que la consulta es válida y está autorizada, se falla
8
+ en cerrado con el código correspondiente.
9
+
10
+ ## 1. Familias
11
+
12
+ | Familia | Qué significa | ¿Reintentable? |
13
+ |---|---|---|
14
+ | **Selección** | No hay proyecto resoluble o hay ambigüedad | Tras acción humana, sí |
15
+ | **Autorización** | El proyecto/ámbito no está permitido | No sin cambio de grants o selección |
16
+ | **Integridad** | Un almacén o el registro no son fiables | No; requiere intervención |
17
+ | **Infraestructura** | Falta el fichero, el perfil o el acceso | Sí, si se restaura el recurso |
18
+ | **Sincronización** | Una raíz no se puede observar de forma completa | Sí, en la siguiente pasada |
19
+
20
+ ## 2. Códigos
21
+
22
+ | Código | Familia | Cuándo | `details` mínimos | Efecto |
23
+ |---|---|---|---|---|
24
+ | `scope-unresolved` | Selección | No hay selección y el cwd no coincide con una raíz registrada | `session_id`, `cwd` | Ninguna consulta; no se abre ningún almacén |
25
+ | `scope-ambiguous` | Selección | El cwd coincide con más de una raíz registrada | `session_id`, `candidates[]` | No se elige una; se pide selección explícita |
26
+ | `scope-forbidden` | Autorización | Proyecto archivado, selección revocada o ámbito no permitido | `session_id`, `project_id?`, `reason` | No se abre el almacén |
27
+ | `scope-too-many` | Autorización | Tras verificar grants, hay más de 8 ámbitos | `project_id`, `libraries[]`, `limit: 8` | No se trunca ni se ignora ninguna; no se abre ninguna biblioteca |
28
+ | `path-excluded` | Autorización | Ruta dentro de una exclusión (Skill Center, almacén propio, `.git`, etc.) | `path`, `reason` | Se rechaza la operación completa |
29
+ | `hardlink-refused` | Autorización | Fichero con más de un enlace duro | `path`, `nlink` | Se rechaza ese fichero; la operación informa |
30
+ | `path-escape` | Autorización | symlink/junction/reparse que sale de la raíz | `path`, `target?` | Se rechaza |
31
+ | `root-overlap` | Autorización | Raíz solapada (padre/hijo) con otra autorizada del perfil, o duplicada global | `path`, `conflictsWith{scopeKind,scopeId,path,relation}` | No se registra la raíz |
32
+ | `root-symlink` | Autorización | La raíz es un enlace, junction o reparse point, o su ruta canónica no coincide con la registrada | `path`, `linkTarget?`, `canonical`, `reason` | No se registra la raíz |
33
+ | `root-changed` | Integridad | El destino real de una raíz registrada cambió (sustitución por junction/symlink, reparse del proveedor) | `path`, `expected?`, `actual` | Se falla en cerrado antes de usar la raíz |
34
+ | `registry-unavailable` | Infraestructura | No existe el registro del perfil o no se puede abrir | `profile_id`, `path?` | Ninguna operación |
35
+ | `registry-corrupt` | Integridad | `integrity_check` falla, `path_key` duplicado, cadena de auditoría rota | `profile_id`, `check`, `detail` | No se escribe; se informa |
36
+ | `scope-store-unavailable` | Infraestructura | Falta el `rag.sqlite3` de un ámbito, está ocupado por otra conexión o sigue migrando | `scope_id`, `scope_kind`, `reason`, `state`, `retryable` | Falla la operación completa: no se entrega un subconjunto que parezca exhaustivo |
37
+ | `scope-store-corrupt` | Integridad | Metadatos incoherentes, `schema_version` futura, `store_state` no `ready`, `integrity_check` o `foreign_key_check` fallan | `scope_id`, `scope_kind`, `check`, `findings?` | No se lee ni se entrega contenido; no se repara solo |
38
+ | `recovery-verification-failed` | Integridad | Una recuperación no pudo verificar recuentos, hashes, FTS5, vectores o auditoría | `scope_id`, `stage`, `check`, `detail` | El almacén en cuarentena queda intacto; no se sustituye |
39
+ | `operation-uncertain` | Integridad | Una operación destructiva quedó `started` (resultado desconocido) o se intenta confirmar con pasos sin completar | `operationId`, `kind`, `operations[]`/`steps[]` | No se repite el efecto; exige reconciliación explícita |
40
+ | `session-invalid` | Selección | `Session.id` ausente o no válido | `session_id?` | No se resuelve |
41
+ | `session-expired` | Selección | La sesión terminó y se conserva la fila `expired` | `session_id`, `project_id` | Se exige nueva selección |
42
+ | `grant-revoked` | Autorización | El grant estaba vigente al iniciar la operación y se revocó durante ella | `project_id`, `scopes[]`, `reason`, `guarantee` | La operación falla en cerrado: no se entrega ningún resultado de ningún ámbito |
43
+ | `sync-root-unavailable` | Sincronización | La raíz no existe, no es accesible o no se puede recorrer por completo | `root_id`, `path`, `code` | No se marca `missing`; se registra `unreadable` |
44
+
45
+ `session-invalid`, `session-expired`, `registry-*` y `scope-store-*` son códigos nuevos de la etapa
46
+ Project-Aware; no existen en v0.1/v0.2 y no se añaden a la superficie pública congelada.
47
+
48
+ **Distinción de sesión:** `session-invalid` = no hay identidad utilizable, o la identidad fue capturada en
49
+ otro perfil (`reason: 'profile-mismatch'`, comprobado por el adaptador antes de abrir el registro);
50
+ `session-expired` = la fila existe en estado `expired`; una selección `invalidated`
51
+ (proyecto archivado, grant/raíz revocada, cambio de perfil, clonación) se informa como `scope-forbidden` con
52
+ `reason`, nunca como `session-invalid`. Un `session_id` sin fila y sin atadura de perfil es indistinguible de
53
+ una sesión nueva: no es inválido; resuelve por `cwd` o falla `scope-unresolved`. No se reutiliza una fila
54
+ `expired`/`invalidated`: se exige una selección nueva.
55
+
56
+ **Revocación durante una operación (semántica única, PA4):** la autorización se fija al inicio como
57
+ **instantánea**, y cada ámbito se revalida antes de abrirse y antes de devolver nada. Si un ámbito pierde la
58
+ autorización durante la operación —grant revocado, sesión expirada o invalidada, proyecto archivado,
59
+ selección cambiada— la operación **falla en cerrado** con `grant-revoked`, `session-expired` o
60
+ `scope-forbidden` y **no entrega ningún resultado**, ni siquiera el parcial de los ámbitos que sí seguían
61
+ autorizados. Motivo: el sobre público de v0.1 (`search`→`{results, mode, elapsedMs}`) no tiene campo donde
62
+ declarar `partial`, y devolver un subconjunto sin declararlo lo haría pasar por exhaustivo (§3, prohibición 3
63
+ de §4). El ámbito afectado y la garantía aplicada viajan en `details.scopes` y `details.guarantee`.
64
+
65
+ Un almacén que se abre con `create: true` porque el proyecto aún no existía es la única creación automática:
66
+ la ausencia de una **biblioteca** nunca se convierte en una biblioteca vacía ni en creación silenciosa; se
67
+ informa `scope-store-unavailable` con `state: 'missing'` y `retryable: false`.
68
+
69
+ ## 3. Clasificación de resultado y visibilidad
70
+
71
+ - **Fallo total:** error propagado; sin resultados parciales. Es el único desenlace posible en v0.1 cuando
72
+ un ámbito autorizado no se puede consultar o pierde la autorización a mitad.
73
+ - **Fallo parcial:** no existe en el sobre público de v0.1. `search` devuelve exactamente
74
+ `{results, mode, elapsedMs}`; `context` devuelve `{text, citations, tokens, truncated, considered}`. No hay
75
+ campo `partial`/`errors` y PA4 **no lo añade**. Internamente el orquestador sigue acumulando el error de
76
+ cada ámbito para auditoría y diagnóstico, pero la operación no devuelve resultados cuando uno falla.
77
+ - **Denegación:** `scope-forbidden`, `path-excluded`, `grant-revoked`; se audita como `denied`.
78
+ - **Estado observado, no error:** que una fuente o una raíz esté `missing` es un estado, no un error de la
79
+ operación. La ausencia de un **almacén de biblioteca** sí es un error de operación (§2).
80
+ - **Propuesta para v0.3 (no implementada, no autorizada):** añadir al sobre de `search` un campo
81
+ `partial: {scopes[], errors[]}` y convertir el fallo total en fallo parcial declarado. Requiere evolución
82
+ del contrato público congelado; queda documentada en `eval/pa4/PA4-DECISIONS.md` (D-PA4-F-01).
83
+
84
+ ## 4. Prohibiciones explícitas
85
+
86
+ 1. Convertir `scope-*` en lista vacía.
87
+ 2. Devolver resultados de otro proyecto como "recuperación parcial".
88
+ 3. Truncar bibliotecas hasta 8 sin decirlo.
89
+ 4. Reintentar con un proyecto distinto cuando el seleccionado falla.
90
+ 5. Reparar automáticamente un registro o almacén corrupto.
91
+ 6. Tratar una lectura fallida como fuente desaparecida (`missing` solo con observación completa).
92
+
93
+ ## 5. Correspondencia futura (no implementada)
94
+
95
+ - En la API v0.3, cada familia tendrá un estado HTTP estable (`400` selección, `403` autorización,
96
+ `409`/`422` integridad, `503` infraestructura); se definirá en el contrato de API.
97
+ - En las herramientas, el error llegará como fallo con `code` en `details`, sin cambiar el sobre actual de
98
+ v0.1 (que no se toca).
99
+ - La UI mostrará el código y un texto humano; nunca un "sin resultados" cuando hubo un error.
100
+
101
+ ## 6. Verificación ejecutada (PA2–PA4)
102
+
103
+ - Prueba por código: se fuerza la condición y se comprueba `code`, `details` y que no se abrió ningún almacén
104
+ cuando el error es de selección/autorización.
105
+ - Prueba de cierre en falso: una biblioteca corrupta, ausente o revocada a mitad hace fallar `search`,
106
+ `context` y `get` sin devolver los resultados del proyecto como si fueran la respuesta completa
107
+ (`lifecode-rag/tests/partial-results.test.mjs`, `lifecode-rag/tests/revocation.test.mjs`).
108
+ - Prueba de no borrado: detectar `missing` no reduce `sources`/`chunks`/`vectors`/auditoría; la recuperación
109
+ conserva el original en cuarentena y valida antes de sustituir
110
+ (`lifecode-rag/tests/recovery.test.mjs`).
111
+ - Prueba de operación incierta: una fila `started` bloquea con `operation-uncertain` y la reconciliación sólo
112
+ cierra la fila (`lifecode-rag/tests/partial-results.test.mjs`).
@@ -0,0 +1,120 @@
1
+ # Contrato de sesión y selección de proyecto (PA0)
2
+
3
+ **Estado:** especificación. No implementado.
4
+ **Decisiones incorporadas:** O-PAR-2 (selección por sesión), O-PAR-3 (bibliotecas anidadas prohibidas),
5
+ O-PAR-4 (registro por perfil), C8 (ciclo de vida de sesión).
6
+
7
+ ## 1. Identidad de sesión
8
+
9
+ - La identidad la crea el **host**: `Session.id` (el mismo que usa DeepSeek Harness). LifeCode RAG no
10
+ inventa identificadores ni usa nombres de conversación.
11
+ - `session_id` es opaco para el plugin: se compara, no se interpreta.
12
+ - Sin `Session.id` disponible → `session-invalid` (no se degrada a "sin proyecto").
13
+ - Une sesión a un proyecto mediante `session_scope(session_id PRIMARY KEY, project_id, …)`.
14
+ - Un `session_id` reutilizado con otro proyecto exige una fila nueva o una actualización explícita con
15
+ `revision` incrementada; nunca se reutiliza una selección vieja en silencio.
16
+ - **Implementación PA2:** el adaptador `lib/session-identity.mjs` captura `agent.id` y la clave del perfil
17
+ activo en ese momento. Una identidad capturada en otro perfil se rechaza con `session-invalid`
18
+ (`reason: 'profile-mismatch'`) antes de tocar el registro. Un `session_id` sin esa atadura, o que no tiene
19
+ fila, es indistinguible de una sesión nueva: no es un error por sí mismo; resuelve por `cwd` o falla
20
+ `scope-unresolved`.
21
+
22
+ ## 2. Ciclo de vida
23
+
24
+ | Evento | Comportamiento | Estado resultante |
25
+ |---|---|---|
26
+ | **Creación de sesión** | No hereda selección. Sin fila → resolución por cwd o `scope-unresolved` | sin selección |
27
+ | **Selección explícita** | Acción humana o del host (`selected_by IN ('human','host')`); se guarda `project_id`, `selection_source='explicit'`, `revision+1` | `active` |
28
+ | **Persistencia** | La fila vive en el registro del perfil; sobrevive al reinicio del host | `active` |
29
+ | **Recuperación tras reinicio** | Se relee por `session_id`; si el proyecto sigue `active` y la sesión no fue invalidada, se restaura | `active` |
30
+ | **Duplicación/clonación** | Un clon recibe **otro** `session_id`; no hereda la fila. Copiar una selección requiere una acción explícita y verificable | sin selección |
31
+ | **Terminación normal** | Se marca `expired` con `expires_at` (no se borra: se conserva para auditoría); una consulta posterior falla `session-expired` | `expired` |
32
+ | **Invalidación** | El host, una persona o una regla de autorización invalidan la selección: `state='invalidated'`, `invalidated_at`, `invalid_reason`; no es una expiración | `invalidated` |
33
+ | **Sesión huérfana** | `session_scope` con proyecto archivado o eliminado lógicamente → `invalidated` con motivo | `invalidated` |
34
+ | **Proyecto archivado** | Selección vigente pasa a `invalidated` con `project-archived`; se exige reselección | `invalidated` |
35
+ | **Selección inválida o revocada** | Proyecto o raíz revocada → `scope-forbidden`; no se cae a otro proyecto | `invalidated` |
36
+ | **Dos sesiones concurrentes** | Filas independientes; cambiar una no afecta a la otra; no hay selección global | ambas `active` |
37
+
38
+ ### 2.1 Transiciones permitidas
39
+
40
+ | Desde | Hacia | Condición | Marca temporal |
41
+ |---|---|---|---|
42
+ | — (sin fila) | `active` | Selección explícita humana/host | `selected_at`, `updated_at`; `revision=1` |
43
+ | `active` | `active` | Reselección explícita | `revision+1`, `updated_at`; `selected_by` requerido |
44
+ | `active` | `expired` | Fin normal de sesión o `expires_at` alcanzado | `expires_at` (obligatorio), `updated_at` |
45
+ | `active` | `invalidated` | Proyecto archivado, grant/raíz revocada, cambio de perfil, clonación, decisión administrativa | `invalidated_at`, `invalid_reason`, `updated_at` |
46
+ | `expired` | `active` | **Prohibida**: una sesión expirada no revive; se selecciona en una sesión nueva | — |
47
+ | `invalidated` | `active` | **Prohibida**; la reselección crea/actualiza una fila nueva de sesión, no reabre la invalidada | — |
48
+
49
+ `expires_at` y `invalidated_at` son excluyentes en la práctica: `expired` exige `expires_at` y prohíbe
50
+ `invalidated_at`; `invalidated` exige `invalidated_at` y `invalid_reason`, y no usa `expires_at`. El
51
+ `CHECK` del contrato de datos lo impone. `revision` se incrementa en cada escritura; nunca hay una
52
+ reselección incremental silenciosa sobre una fila `expired`/`invalidated`.
53
+
54
+ La selección **nunca** la crea una herramienta del modelo (ni `ingest`, ni `search`, ni `context`). Si una
55
+ herramienta necesita proyecto y no lo hay, devuelve error; no elige por su cuenta.
56
+
57
+ ## 3. Resolución del ámbito
58
+
59
+ Orden normativo, sin atajos:
60
+
61
+ 1. **Selección explícita activa** de la sesión → proyecto de esa fila.
62
+ 2. Si no hay selección: **cwd de la sesión** (resuelto por el host) contra `roots.path_key` de
63
+ proyectos `active` (`roots.scope_kind='prj'`, `roots.state='authorized'`). Debe coincidir con
64
+ **exactamente una** raíz autorizada.
65
+ - 0 coincidencias → `scope-unresolved`.
66
+ - 2 o más coincidencias (raíces superpuestas o duplicadas) → `scope-ambiguous`.
67
+ 3. **Nunca** se usa un proyecto "por defecto" global, el último usado, ni el primero del registro.
68
+ 4. El cwd es un mecanismo de resolución, no una autorización: si la raíz no está registrada y autorizada,
69
+ no vale.
70
+ 5. Si la selección apunta a un proyecto cuyo estado ya no es `active` → `scope-forbidden`.
71
+
72
+ ## 4. Reglas de aislamiento
73
+
74
+ - Una sesión tiene **como máximo un** proyecto activo.
75
+ - Dos sesiones pueden estar en proyectos distintos a la vez; ninguna escritura de selección toca la otra.
76
+ - El registro es del perfil: una sesión de otro perfil no puede leer este registro, ni siquiera con el mismo
77
+ `session_id` (el perfil forma parte del contrato de resolución; `profile_id` se comprueba al abrir).
78
+ - Un `session_id` de otro perfil se trata como inexistente en este; no se "repara" copiando filas.
79
+
80
+ ## 5. Proyecto archivado o eliminado
81
+
82
+ - Archivar: `projects.status='archived'`, `archived_at`; no borra almacén, raíces, `sync_state` ni auditoría.
83
+ - Las sesiones con ese proyecto quedan `invalidated` con `invalid_reason='project-archived'`.
84
+ - Consultar con una sesión invalidada → `scope-forbidden`; el mensaje incluye el proyecto y el motivo, sin
85
+ revelar contenido.
86
+ - Borrado definitivo de un proyecto es una operación humana con aprobación y copia previa; no ocurre por
87
+ automatización.
88
+
89
+ ## 6. Interacción con herramientas (contrato futuro v0.3)
90
+
91
+ - Las siete herramientas v0.1 **no cambian** y no aceptan `project_id` ni `scope_id`.
92
+ - La resolución ocurre dentro del adaptador, antes de abrir almacenes.
93
+ - Para v0.3 se propone una referencia pública `<scope_id>:<source_id>`; su semántica se define en el
94
+ contrato v0.3, no aquí. PA0 no la implementa.
95
+ - Si en el futuro existe una acción de selección expuesta al usuario, será una acción de interfaz o del
96
+ host, nunca una herramienta invocable por el modelo sin aprobación.
97
+
98
+ ## 7. Persistencia y límites
99
+
100
+ - La tabla no crece sin control: las filas `expired`/`invalidated` se conservan N días (propuesta: 90) y
101
+ luego se purgan con auditoría; el proyecto y sus datos no se tocan.
102
+ - La selección no se guarda en `localStorage` ni en el cliente: el cliente no es fuente de verdad.
103
+ - Si el registro no está disponible: `registry-unavailable`; no se usa una copia en memoria como sustituto
104
+ silencioso.
105
+
106
+ ## 8. Casos que deben probarse en PA2
107
+
108
+ | Caso | Resultado esperado |
109
+ |---|---|
110
+ | Sesión A selecciona P1; sesión B selecciona P2 | Cada una ve solo su proyecto; sin interferencia |
111
+ | Reinicio del host con sesiones activas | Ambas selecciones se recuperan |
112
+ | Clonar una sesión | El clon no hereda selección |
113
+ | Sesión termina y vuelve a consultar | `session-expired` |
114
+ | Proyecto archivado | `scope-forbidden` con motivo |
115
+ | cwd dentro de dos raíces registradas | `scope-ambiguous` |
116
+ | cwd fuera de toda raíz | `scope-unresolved` |
117
+ | `session_id` de otro perfil | Tratado como inexistente → `scope-unresolved` |
118
+ | Sesión expirada que intenta reactivarse | Rechazado; se exige sesión nueva (`session-expired`) |
119
+ | Selección revocada mientras corre una consulta | La consulta en curso termina con la instantánea de autorización; la siguiente falla `scope-forbidden` |
120
+ | Grant revocado mientras corre una consulta | Ámbitos ya abiertos terminan; los no abiertos se omiten con `grant-revoked`; respuesta `partial:true` |