@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,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` |
|