@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.
- package/LICENSE +21 -0
- package/README.md +220 -2
- package/bin/lifecode-rag.mjs +449 -0
- package/client.js +3515 -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 +887 -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 +231 -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 +946 -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 +606 -0
- package/lib/resolve.mjs +318 -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 +225 -0
- package/lib/server.mjs +340 -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,887 @@
|
|
|
1
|
+
# PA-UI-0 — Contrato de API visual Project-Aware
|
|
2
|
+
|
|
3
|
+
**Proyecto:** LifeCode RAG · **Fase:** PA-UI-0 (diseño contractual, sin implementación)
|
|
4
|
+
**Versión del contrato de UI:** `pa-ui/0.1.0-draft` (revisión 3) · **Estado:** PROPOSED — pendiente de aprobación humana
|
|
5
|
+
**Contrato de herramientas vigente:** v0.1.0, **congelado** (`docs/CONTRATO-v0.1.md`, SHA-256 `a58db7d6cac0756e2711c5ef556111dc7d38cec206420021e2bc42e42b4068f1`)
|
|
6
|
+
**Host de referencia:** DeepSeek Harness 0.2.2-rc.5 · **Plugin:** `lifecode-rag/` 1.0.0
|
|
7
|
+
**Fecha:** 2026-11-18 · **Revisiones:** PA-UI-0.1 y PA-UI-0.2 (ver §13 y §14)
|
|
8
|
+
|
|
9
|
+
> **Resultado de la revisión PA-UI-0.1: `BLOCKED` en el punto PA01.** El host no ofrece hoy una primitiva verificada que ligue una petición HTTP a una sesión de conversación (evidencia en §3.4). Este contrato deja de presentar la cabecera de sesión como autenticación: la trata como **referencia de direccionamiento** sobre un peer ya autenticado por el host como `owner`, y declara el riesgo residual como decisión humana pendiente. Los demás puntos (PA02–PA05) quedan resueltos documentalmente. Ver `docs/PA-UI-0.1-REVIEW.md`.
|
|
10
|
+
|
|
11
|
+
> **Revisión PA-UI-0.2 (documental):** auditoría `ui.read` append-only sin dedupe (§7.1), `actor` de origen humano sin pretensión de identidad autenticada, GAP-20 como `OPEN / DOCUMENTED HOST LIMITATION` y ruta topológica `NOT DEMONSTRATED` (§3.6, D-UI-11). El resultado global sigue `BLOCKED`; PA-UI-1 no se inicia. Ver `docs/PA-UI-0.2-REVIEW.md`.
|
|
12
|
+
|
|
13
|
+
> Este documento **no implementa** nada. Define el contrato que PA-UI-1 deberá implementar.
|
|
14
|
+
> No modifica las siete herramientas públicas v0.1, ni `package.json`, ni `index.js`, ni `client.js`.
|
|
15
|
+
> Cada afirmación lleva su origen: `[IMPLEMENTED]` (existe en el código), `[VERIFIED HOST]` (demostrado en el host vivo), `[DOCUMENTED]` (está en documentación), `[PROPOSED]` (diseño nuevo), `[GAP]` (capacidad ausente), `[UNKNOWN]` (sin evidencia suficiente).
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## 1. Objetivo y alcance
|
|
20
|
+
|
|
21
|
+
La interfaz visual Project-Aware permite a una persona, dentro de DeepSeek Harness:
|
|
22
|
+
|
|
23
|
+
1. ver el proyecto activo de su sesión y su estado de autorización;
|
|
24
|
+
2. seleccionar explícitamente un proyecto para esa sesión;
|
|
25
|
+
3. ver las bibliotecas concedidas y sus permisos efectivos;
|
|
26
|
+
4. listar y abrir las fuentes indexadas del proyecto;
|
|
27
|
+
5. buscar sobre los ámbitos efectivos;
|
|
28
|
+
6. ver el contexto recuperado con sus citas;
|
|
29
|
+
7. entender los errores de acceso y autorización.
|
|
30
|
+
|
|
31
|
+
**Fuera de alcance en este contrato:** ingesta, borrado, reindexación, configuración, métricas históricas, exportación de auditoría, cualquier escritura distinta de la selección de proyecto.
|
|
32
|
+
|
|
33
|
+
La UI es una **capa de lectura** sobre la misma arquitectura de autorización de las herramientas. No crea una segunda ruta de autorización: toda petición termina en `withAuthorizedContext` o en el mismo resolutor que usan las herramientas (`resolveScope`, `registerSelection`, `openRegistry`).
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
## 2. Principios de diseño
|
|
38
|
+
|
|
39
|
+
| # | Principio | Origen |
|
|
40
|
+
|---|---|---|
|
|
41
|
+
| P1 | La identidad de sesión la compone el host, nunca el navegador ni el modelo. | `[IMPLEMENTED]` `lib/session-identity.mjs` (`captureSession` usa sólo `agent.id`) |
|
|
42
|
+
| P2 | Antes de abrir un almacén se resuelve sesión, proyecto, grants y ámbitos. | `[IMPLEMENTED]` `lib/exec-context.mjs`, `lib/resolve.mjs` |
|
|
43
|
+
| P3 | Fallo cerrado: sin identidad, sin selección o con grant revocado no se devuelven datos. | `[IMPLEMENTED]` PA2/PA3 |
|
|
44
|
+
| P4 | Sin fallback al almacén único v0.2 ni a búsqueda global. | `[IMPLEMENTED]` `index.js` sólo monta la API v0.2 si existe `rag.sqlite3`; `[GAP]` no hay API Project-Aware |
|
|
45
|
+
| P5 | El navegador envía **referencias**, no pruebas de autorización. | `[PROPOSED]` (ver §4) |
|
|
46
|
+
| P6 | Los identificadores de otra sesión no son visibles, y los de ámbitos no autorizados no se aceptan. | `[PROPOSED]` (ver §9) |
|
|
47
|
+
| P7 | Una sola ruta de apertura de almacenes: `ctx.open(scope, {create:false})`. | `[IMPLEMENTED]` `lib/exec-context.mjs` |
|
|
48
|
+
| P8 | Toda lectura revalida cuando corresponde y cierra recursos en `finally`. | `[IMPLEMENTED]` `ctx.checkpoint`, `ctx.revalidate` |
|
|
49
|
+
| P9 | La selección de proyecto es una acción humana registrada y auditada. | `[IMPLEMENTED]` `lib/sessions.mjs` `registerSelection` (`selectedBy`, `actor`) |
|
|
50
|
+
| P10 | Las siete herramientas v0.1 no se tocan; la API visual es un contrato separado y aditivo. | `[DOCUMENTED]` orden PA-UI-0 §9 |
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## 3. Identidad: cómo llega la sesión al backend
|
|
55
|
+
|
|
56
|
+
### 3.1 Cadena real (evidencia)
|
|
57
|
+
|
|
58
|
+
- El host expone `ctx.agents.get(id: SessionId): Agent | undefined` y `list(): Agent[]`; `Agent` es `{ readonly id: SessionId }` y el propio contrato dice que el id es **el id compartido de agente y sesión**. `[VERIFIED HOST]` (catálogo de servicios del host).
|
|
59
|
+
- El slot de cliente `conversation.session.header.actions` es de `scope: 'session'` y entre sus *standard props* entrega `sessionId: SessionId`, `useSession`, `useAccess`, `useChat`, entre otros. `[VERIFIED HOST]` (catálogo de slots del cliente).
|
|
60
|
+
- El plugin `lifecode-skill-center` ya usa exactamente ese mecanismo: registra un ocupante oculto `lifecode-skill-center.session-probe` (order 60) en ese slot y recibe el `sessionId` de la conversación; el probe «no pinta nada». `[VERIFIED HOST]` (ocupantes del slot) + `[IMPLEMENTED]` en `lifecode-skill-center/client.js` (`SESSION_ACTIONS_SLOT`, `SessionToastProbe`, `sessions.binding(id)`).
|
|
61
|
+
- El host entrega el `sessionId` al **cliente** como dato de presentación; no lo entrega al backend como prueba. Que el cliente conozca ese id no demuestra que la petición HTTP venga de esa pestaña.
|
|
62
|
+
|
|
63
|
+
### 3.2 Qué autentica realmente el host (evidencia PA-UI-0.1)
|
|
64
|
+
|
|
65
|
+
`[VERIFIED HOST]` (fuentes del host leídas en `app.asar`, sólo lectura):
|
|
66
|
+
|
|
67
|
+
| Hecho | Fuente |
|
|
68
|
+
|---|---|
|
|
69
|
+
| La autenticación del navegador es un **token de lanzamiento por proceso** canjeado por una cookie firmada ligada a la **autoridad** (host+puerto), con `issuedAt`/`expiresAt` (30 días por defecto) y sin operación de logout. | `@deepseek-ai/dsh-client-connection/src/browser-auth.ts` (`AUTH_RECORD_KEY`, payload `{version, authority, issuedAt, expiresAt}`, `cookieMaxAgeDays` default 30) |
|
|
70
|
+
| El *trust fence* comprueba `Host`, `Origin` y `sec-fetch-site`; su propio comentario dice: **«this fence never establishes identity»**. | `dsh-client-connection/src/api-request-trust.ts:12` |
|
|
71
|
+
| Todo el navegador autenticado comparte **un** `browserPeer` con `principal: { kind: 'owner' }`; no existe un nivel de autenticación por método ni por sesión. | `dsh-client-connection/README.md` líneas 41–51 |
|
|
72
|
+
| El `principal` de un `Peer` se fija en su construcción; un Peer in-process se crea con `createPeer({principal})`, no a partir de la petición. | `dsh-client-connection/src/peer.ts:16` |
|
|
73
|
+
| El control de acceso por rol (`remoteAccess`) **sólo se aplica a peers no-owner**; al owner nunca se le comprueba. | `dsh-api-remote-access/README.md` («The owner … is never checked») |
|
|
74
|
+
| Las propias APIs de sesión del host reciben el `sessionId` **como parámetro de direccionamiento** del llamante; el Gateway resuelve el recurso y aplica `remoteAccess` sólo a no-owner. | `dsh-api-session-controller/src/index.ts:85–104`, `:284`, `:298` |
|
|
75
|
+
|
|
76
|
+
**Conclusión de PA01:** no existe hoy en el host una primitiva verificada —token por sesión, capacidad efímera, cookie por pestaña, RPC con identidad de conversación— que permita a un plugin demostrar que una petición HTTP pertenece a una sesión concreta. Cualquier proceso local que obtenga la cookie del GUI (o el token de lanzamiento) puede hablar como `owner` y **nombrar** cualquier `sessionId` vivo. `ctx.agents.get(id)` sólo demuestra que ese agente existe; no demuestra quién llama. Por tanto **PA01 queda `BLOCKED`** y D-UI-03 no se declara resuelto.
|
|
77
|
+
|
|
78
|
+
### 3.3 Contrato de transporte: referencia de direccionamiento, no credencial
|
|
79
|
+
|
|
80
|
+
`[PROPOSED]` La mitad cliente de RAG registra su propio probe mudo en `conversation.session.header.actions`, recibe el `sessionId` y lo envía en la cabecera:
|
|
81
|
+
|
|
82
|
+
```
|
|
83
|
+
x-lifecode-rag-session: <sessionId>
|
|
84
|
+
x-lifecode-rag: 1 (obligatoria en POST)
|
|
85
|
+
content-type: application/json (obligatoria en POST)
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Reglas no negociables (deterministas):
|
|
89
|
+
|
|
90
|
+
1. El backend **no** acepta `sessionId` en query string, cuerpo JSON ni cookies; si aparece en el cuerpo, la petición se rechaza con `400 invalid-argument` `reason: unknown-field` (PA02).
|
|
91
|
+
2. La cabecera es **obligatoria** en toda ruta de datos. Ausente o con forma inválida (`^[\x20-\x7e]{1,200}$`) → `401 session-invalid`. Un valor válido no se interpreta nunca como prueba de autorización.
|
|
92
|
+
3. El backend comprueba que exista un **agente vivo** con `ctx.agents.get(sessionId)`; si no existe → `409 session-unavailable`. La comprobación es de *direccionamiento* (¿hay algo que atender en esa dirección?), no de identidad.
|
|
93
|
+
4. Con el `Agent` en mano se construye `exec = { agent, callId, signal }` y se llama a `withAuthorizedContext({ services, exec }, work)`; la identidad efectiva sigue siendo `agent.id`, jamás el string recibido. `[IMPLEMENTED]`
|
|
94
|
+
5. La API **no afirma** en ningún documento, mensaje ni cabecera que la sesión esté autenticada. El único sujeto autenticado es el peer `owner` del host; la sesión es el **recurso direccionado**.
|
|
95
|
+
6. La autorización real (proyecto, grants, ámbitos, almacenes) la sigue decidiendo `resolveScope`/`withAuthorizedContext`; la cabecera no concede nada por sí sola.
|
|
96
|
+
|
|
97
|
+
### 3.4 Alternativas evaluadas para PA01 (y por qué no resuelven)
|
|
98
|
+
|
|
99
|
+
| # | Alternativa | Viabilidad con el host actual | Veredicto |
|
|
100
|
+
|---|---|---|---|
|
|
101
|
+
| A | Capacidad/token **emitido por el host** por sesión, validable en backend, revocable al cerrar | No existe API: `browser-auth` sólo emite cookies por autoridad; `agents` no emite capacidades; `connection` no expone token por peer a plugins | **BLOQUEADA** — requeriría cambio del host |
|
|
102
|
+
| B | Capacidad **emitida por el plugin** al cargar el panel, ligada a `sessionId` | El endpoint que la emitiría corre sobre el mismo canal `owner`; cualquier proceso local puede pedir una para otra sesión. No distingue pestañas ni demuestra propiedad | **RECHAZADA** — no añade garantía, sólo complejidad |
|
|
103
|
+
| C | Ligar la capacidad al `peer.id` de la cookie v2 (`/connect`) | El peer se crea con el token de lanzamiento; el plugin no puede saber qué pestaña es. `peer.id` es del peer, no de la conversación | **RECHAZADA** |
|
|
104
|
+
| D | Aislar por topología: instancia de host / `DSH_HOME` / perfil dedicados, sin otras sesiones en el proceso | Reduce la superficie (no hay otras sesiones a las que direccionar), pero **no** aporta una prueba de identidad del emisor | **MITIGACIÓN DE SUPERFICIE** — sólo válida si se demuestran los criterios TI-1…TI-7 de §3.6; hoy `NOT DEMONSTRATED` |
|
|
105
|
+
| E | Mantener la cabecera como direccionamiento + auditoría + fence del host, con el riesgo documentado | Es lo único compatible sin tocar el host; el riesgo residual es idéntico al de las APIs de sesión del propio host | **ÚNICA VÍA DISPONIBLE**, supeditada a una decisión humana explícita e independiente (D-UI-03), **no otorgada** por PA-UI-0.2 |
|
|
106
|
+
|
|
107
|
+
### 3.5 Riesgo residual (documentado, no oculto)
|
|
108
|
+
|
|
109
|
+
El peer HTTP del navegador es siempre `principal: { kind: 'owner' }` y el host no transporta identidad de sesión. `[VERIFIED HOST]` (`connection.browserPeer`; `remoteAccess` sólo para no-owner). Consecuencias, sin adornos:
|
|
110
|
+
|
|
111
|
+
- Cualquier proceso local con la cookie del GUI o el token de lanzamiento puede **direccionar** otra sesión viva. La API visual no puede impedirlo por sí sola.
|
|
112
|
+
- Este riesgo es **el mismo** que tienen las APIs de sesión nativas del host (reciben `sessionId` del llamante owner); no es una regresión introducida por RAG, pero tampoco desaparece por repetir que existe.
|
|
113
|
+
- Mitigaciones obligatorias en PA-UI-1: admisión del host (`connection.requestRejection`), `assertLoopback` (Host/Origin loopback), cabecera personalizada + `content-type: application/json`, ausencia de CORS, `ui.read` auditado (PA03), y mensajes de error que no permitan enumerar sesiones/proyectos.
|
|
114
|
+
- **Estado:** `BLOCKED` para autenticación de sesión (PA01). La limitación del host queda **`OPEN / DOCUMENTED HOST LIMITATION`**: no hay aceptación humana del riesgo, y documentarla no equivale a aceptarla. `PENDING HUMAN DECISION` para D-UI-03. Sin esa decisión, PA-UI-1 no puede declarar la parte de identidad como cumplida.
|
|
115
|
+
|
|
116
|
+
### 3.6 Ruta alternativa de mitigación: aislamiento topológico (no es autenticación)
|
|
117
|
+
|
|
118
|
+
`[PROPOSED]` Esta ruta se documenta porque puede **reducir la superficie** de PA01 sin tocar el host. No se presenta en ningún caso como autenticación ni como capacidad de sesión, y **no se ha ejecutado ni verificado** en PA-UI-0.2.
|
|
119
|
+
|
|
120
|
+
**Distinción obligatoria**, que debe repetirse en todos los documentos:
|
|
121
|
+
|
|
122
|
+
| Concepto | Qué es | Qué no es |
|
|
123
|
+
|---|---|---|
|
|
124
|
+
| Autenticación/capacidad de sesión | prueba verificable de que el emisor está autorizado para actuar sobre **esa** sesión | no existe hoy en el host (PA01) |
|
|
125
|
+
| Aislamiento topológico | separación operativa del proceso y de sus sesiones para que no haya otras sesiones a las que direccionar | **no** demuestra quién envía una petición; no sustituye a la autenticación |
|
|
126
|
+
|
|
127
|
+
Criterios mínimos para poder declarar la ruta como **DEMOSTRADA** (todos, con evidencia reproducible y responsable de verificación):
|
|
128
|
+
|
|
129
|
+
| # | Criterio |
|
|
130
|
+
|---|---|
|
|
131
|
+
| TI-1 | Proceso Harness **dedicado** al entorno RAG (una instancia, un `DSH_HOME`/perfil, sin plugins de terceros innecesarios). |
|
|
132
|
+
| TI-2 | **Ausencia** de otras conversaciones/sesiones no autorizadas dentro de ese mismo proceso (listado de agentes del proceso = sólo las autorizadas). |
|
|
133
|
+
| TI-3 | Evidencia verificable de que las solicitudes del plugin **no pueden direccionar** sesiones de otros procesos o instancias (p. ej. el proceso aislado no comparte el bus/almacén de sesiones con el resto). |
|
|
134
|
+
| TI-4 | Ausencia de mecanismos compartidos que permitan saltar la frontera (misma cookie/token de GUI reutilizable contra la instancia aislada, mismo puerto expuesto, proxy común, almacén de sesiones compartido). |
|
|
135
|
+
| TI-5 | Procedimiento operativo documentado: iniciar, mantener, cerrar y **verificar** el aislamiento (incluye qué hacer si se abre una segunda instancia). |
|
|
136
|
+
| TI-6 | Prueba reproducible de que una sesión externa no puede ser alcanzada desde el proceso aislado (o de que no existe). |
|
|
137
|
+
| TI-7 | Evidencia y **responsable de la verificación** registrados; revisión humana de la frontera. |
|
|
138
|
+
|
|
139
|
+
**Estado: `NOT DEMONSTRATED`.** No se ha ejecutado ninguna prueba de aislamiento (PA-UI-0.2 es documental) y no se ha modificado la topología. Un perfil dedicado, un `DSH_HOME` separado o una instalación aparte **no** demuestran por sí solos TI-1…TI-7. La ruta sólo puede pasar a `DEMONSTRATED` con evidencia de los siete criterios; hasta entonces, G6 sigue `BLOCKED` (§L de `PA-UI-0-ACCEPTANCE.md`).
|
|
140
|
+
|
|
141
|
+
---
|
|
142
|
+
|
|
143
|
+
## 4. Flujo de autorización de una petición
|
|
144
|
+
|
|
145
|
+
```
|
|
146
|
+
HTTP request
|
|
147
|
+
→ host: cookie del GUI / trust fence (Host, Origin, sec-fetch-site) [VERIFIED HOST] (401 si no autenticado)
|
|
148
|
+
→ connection.requestRejection(req) [VERIFIED HOST]
|
|
149
|
+
→ assertLoopback (Host + Origin loopback) [IMPLEMENTED] patrón de lib/server.mjs
|
|
150
|
+
→ x-lifecode-rag-session header → assertSessionId [IMPLEMENTED]
|
|
151
|
+
· ausente o inválida → 401 session-invalid
|
|
152
|
+
→ ctx.agents.get(sessionId) → Agent vivo | 409 session-unavailable [VERIFIED HOST] API
|
|
153
|
+
→ abrir auditoría de lectura: correlationId = UUID, t0 = now() [PROPOSED] (PA03)
|
|
154
|
+
→ openRegistry({create:false}) [IMPLEMENTED]
|
|
155
|
+
· store-not-initialized → 503 registry-unavailable (no crea nada)
|
|
156
|
+
→ getSession / resolveScope (denegaciones ya auditadas) [IMPLEMENTED]
|
|
157
|
+
→ withAuthorizedContext({services, exec}, work) [IMPLEMENTED]
|
|
158
|
+
· scopes efectivos, revalidación, apertura perezosa autorizada
|
|
159
|
+
→ ctx.open(scope, {create:false}) por ámbito autorizado [IMPLEMENTED]
|
|
160
|
+
→ operación de lectura (searchScopes / contextScopes / listProject / getSource)
|
|
161
|
+
→ ctx.checkpoint(...) antes de devolver [IMPLEMENTED]
|
|
162
|
+
→ ui.read: appendRegistryAudit({action:'ui.read', outcome, durationMs}) [PROPOSED] (PA03; fail-closed)
|
|
163
|
+
→ respuesta + cabecera x-lifecode-rag-request: <correlationId>
|
|
164
|
+
→ finally: cierre de cada almacén abierto y del registro [IMPLEMENTED]
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
La selección (`POST /selection`) es la única escritura: pasa por `registerSelection`, que ya valida perfil, sesión y proyecto, y audita `session.select` / `session.reselect`. `[IMPLEMENTED]`
|
|
168
|
+
|
|
169
|
+
Aclaración de comportamiento `[IMPLEMENTED]` `lib/resolve.mjs`:
|
|
170
|
+
|
|
171
|
+
- Sin selección y sin `cwd` → `scope-unresolved`.
|
|
172
|
+
- Sin selección y `cwd` fuera de toda raíz → `scope-unresolved`.
|
|
173
|
+
- `cwd` dentro de varias raíces → `scope-ambiguous`.
|
|
174
|
+
- Selección explícita + `cwd` que cae en **otro** proyecto → `scope-ambiguous`.
|
|
175
|
+
- Selección explícita + `cwd` fuera de toda raíz → se acepta la selección (el `cwd` no restringe).
|
|
176
|
+
- Proyecto archivado → `scope-forbidden` `reason: project-archived`.
|
|
177
|
+
- Sesión expirada / invalidada → `session-expired` / `scope-forbidden`.
|
|
178
|
+
|
|
179
|
+
---
|
|
180
|
+
|
|
181
|
+
## 5. Superficie de la API
|
|
182
|
+
|
|
183
|
+
Prefijo propuesto: **`/lifecode-rag/ui/api`** `[PROPOSED]`. No se reutiliza `/lifecode-rag/api` (API v0.2 heredada, DOCUMENTED) ni se monta cuando no hay almacén legado.
|
|
184
|
+
|
|
185
|
+
Envoltorio de respuesta (mismo sobre que la API v0.2, para no introducir un tercer estilo) `[DOCUMENTED]` `lib/server.mjs`:
|
|
186
|
+
|
|
187
|
+
```json
|
|
188
|
+
{ "ok": true, "data": { } }
|
|
189
|
+
{ "ok": false, "error": { "code": "scope-forbidden", "message": "…", "details": { } } }
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
> **Implementación LE-RAG-12.** `lib/pa-api.mjs` produce ese sobre en `writeJson`: el payload de cada ruta
|
|
193
|
+
> viaja dentro de `data` y los fallos dentro de `error`, sin `data` y con el status del código. El cliente
|
|
194
|
+
> (`client.js`) lo desenvuelve en un solo punto (`request`) y trata `ok:false` como fallo **aunque llegue con
|
|
195
|
+
> 200**, para que un defecto del servidor no se degrade a datos vacíos. Un cuerpo que excede el tope no se
|
|
196
|
+
> sirve: se responde `500 response-too-large`.
|
|
197
|
+
|
|
198
|
+
### 5.1 Resumen de rutas
|
|
199
|
+
|
|
200
|
+
| Método | Ruta | Autorización | Escritura | Propósito |
|
|
201
|
+
|---|---|---|---|---|
|
|
202
|
+
| GET | `/health` | ninguna (sin datos de sesión) | no | Estado del servicio y versiones |
|
|
203
|
+
| GET | `/session` | cabecera de sesión | no | Sesión, selección, proyecto, ámbitos, estado |
|
|
204
|
+
| GET | `/projects` | cabecera de sesión | no | Proyectos seleccionables por esta sesión |
|
|
205
|
+
| POST | `/selection` | cabecera de sesión | **sí** (selección) | Registrar selección explícita |
|
|
206
|
+
| GET | `/libraries` | cabecera de sesión | no | Bibliotecas concedidas + estado de almacén |
|
|
207
|
+
| GET | `/sources` | cabecera de sesión | no | Fuentes del proyecto activo (paginado) |
|
|
208
|
+
| GET | `/sources/:id` | cabecera de sesión | no | Fuente + fragmentos (proyecto activo) |
|
|
209
|
+
| POST | `/search` | cabecera de sesión | no | Búsqueda en ámbitos efectivos |
|
|
210
|
+
| POST | `/context` | cabecera de sesión | no | Contexto recuperado + citas |
|
|
211
|
+
| GET | `/diagnostics` | cabecera de sesión | no | Diagnóstico redactado de la sesión |
|
|
212
|
+
|
|
213
|
+
> **Implementado en `pa/1.1.0` (ACP-01, §15).** La superficie viva de este build es
|
|
214
|
+
> `GET /lifecode-rag/pa/snapshot`, `GET /config`, `POST /search`, `POST /context`, `POST /selection` y
|
|
215
|
+
> `POST /actions` (siempre 403). Las rutas `/session`, `/projects`, `/libraries`, `/sources`,
|
|
216
|
+
> `/sources/:id`, `/diagnostics` y `/health` de esta tabla siguen siendo **diseño**: no hay contrato
|
|
217
|
+
> implementado y el panel no las consume. La autorización no es una cabecera de sesión (§3.2, PA01):
|
|
218
|
+
> es la credencial del host, verificada por `ctx.connection` en el adaptador.
|
|
219
|
+
|
|
220
|
+
Todas las rutas de datos exigen `x-lifecode-rag-session`. `POST` exige además `x-lifecode-rag: 1` y `content-type: application/json` (patrón ya usado por la API v0.2, `[IMPLEMENTED]` `assertWrite`).
|
|
221
|
+
|
|
222
|
+
Reglas transversales de la superficie (PA02/PA03):
|
|
223
|
+
|
|
224
|
+
- **Campos desconocidos = rechazo.** Todo `POST` valida su esquema de forma estricta: una clave no declarada produce `400 invalid-argument` con `reason: "unknown-field"` y `details.fields: ["…"]` (sólo nombres, nunca valores) y **no se ejecuta la operación**. Aplica a `/selection`, `/search` y `/context`.
|
|
225
|
+
- **Parámetros de query desconocidos = rechazo.** `GET` acepta sólo los parámetros declarados por ruta; cualquier otro (`projectId`, `scope`, `sessionId`, …) produce `400 invalid-argument` con `reason: "unknown-parameter"` y `details.parameters` (nombres). No se ignora nada en silencio.
|
|
226
|
+
- **Correlación.** El servidor genera un `correlationId` (UUID v4) por petición, lo devuelve en la cabecera de respuesta `x-lifecode-rag-request` y lo usa como `call_id` del evento `ui.read`. La persona puede citarlo al reportar un problema; nunca se acepta uno enviado por el cliente.
|
|
227
|
+
- **Sin CORS.** La API no emite cabeceras `Access-Control-Allow-*`; un `Origin` de otra autoridad se rechaza antes de entrar (H-01/H-02).
|
|
228
|
+
- **Cuerpo máximo.** 1 MiB (PA05); por encima, `413 too-large` sin leer el resto.
|
|
229
|
+
|
|
230
|
+
---
|
|
231
|
+
|
|
232
|
+
## 6. Esquemas por capacidad
|
|
233
|
+
|
|
234
|
+
Convención: `EXISTENTE` = campo que ya produce el código; `DERIVABLE` = dato en el modelo pero no proyectado hoy; `GAP` = no existe.
|
|
235
|
+
|
|
236
|
+
### 6.1 `GET /session`
|
|
237
|
+
|
|
238
|
+
Devuelve el estado **sin abrir almacenes** cuando no hay selección, y con ámbitos cuando la hay.
|
|
239
|
+
|
|
240
|
+
```json
|
|
241
|
+
{
|
|
242
|
+
"api": "pa-ui/0.1.0-draft",
|
|
243
|
+
"contract": "0.1.0",
|
|
244
|
+
"session": {
|
|
245
|
+
"id": "session-…",
|
|
246
|
+
"profileKey": "desktop",
|
|
247
|
+
"state": "active | expired | invalidated | none",
|
|
248
|
+
"invalidReason": "project-archived | grant-revoked | root-revoked | profile-changed | admin | session-cloned | null",
|
|
249
|
+
"expiresAt": null,
|
|
250
|
+
"selection": {
|
|
251
|
+
"state": "active | none | unresolvable | ambiguous",
|
|
252
|
+
"projectId": "prj_…",
|
|
253
|
+
"projectName": "…",
|
|
254
|
+
"source": "explicit | cwd",
|
|
255
|
+
"revision": 3,
|
|
256
|
+
"selectedBy": "human | host",
|
|
257
|
+
"selectedAt": 1763…,
|
|
258
|
+
"candidates": [{ "projectId": "prj_…", "path": "<redactado>" }]
|
|
259
|
+
}
|
|
260
|
+
},
|
|
261
|
+
"project": { "id": "prj_…", "name": "…", "status": "active" },
|
|
262
|
+
"scopes": [
|
|
263
|
+
{ "kind": "prj", "id": "prj_…", "name": "…", "roots": 1, "store": "present | missing | migrating | corrupt" },
|
|
264
|
+
{ "kind": "lib", "id": "lib_…", "name": "…", "roots": 1, "store": "present | missing | corrupt", "permission": "read" }
|
|
265
|
+
],
|
|
266
|
+
"scopeCount": 3,
|
|
267
|
+
"service": { "status": "ok | degraded", "registry": "ok | unavailable | corrupt", "storeRoot": "ready | missing" }
|
|
268
|
+
}
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
Origen por bloque: `session.state/invalidReason` = `session_scope` `[EXISTENTE]`; `selection.*` = `session_scope` `[EXISTENTE]` (la fila no guarda `projectName`: se resuelve con `getProject`) `[EXISTENTE]`; `scopes[].roots` = `effectiveScopes` `[EXISTENTE]`; `store` = `library-state` / `scopeStoreExists` `[EXISTENTE]`; `service.registry/storeRoot` = comprobaciones de `openRegistry` + `profileRoot` `[EXISTENTE]`; `service.status` = `[PROPOSED]` (degradado si alguna biblioteca concedida está `missing`/`corrupt`).
|
|
272
|
+
|
|
273
|
+
`unresolvable` / `ambiguous` se obtienen capturando `scope-unresolved` / `scope-ambiguous` de `resolveScope` — que **ya audita la denegación** — sin convertir el error en datos de otro proyecto. `[PROPOSED]` (hoy `withAuthorizedContext` propaga el error).
|
|
274
|
+
|
|
275
|
+
### 6.2 `POST /selection`
|
|
276
|
+
|
|
277
|
+
Esquema **estricto** de petición (PA02):
|
|
278
|
+
|
|
279
|
+
```json
|
|
280
|
+
{ "projectId": "prj_…", "expectedRevision": 3 }
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
| Campo | Tipo | Obligatorio | Regla |
|
|
284
|
+
|---|---|---|---|
|
|
285
|
+
| `projectId` | string `prj_…` | sí | Debe existir, estar `active` y ser candidato (§6.3). |
|
|
286
|
+
| `expectedRevision` | entero ≥ 0 | sí | Revisión que el cliente cree vigente. `0` = «no hay selección todavía». |
|
|
287
|
+
|
|
288
|
+
Cualquier otra clave → `400 invalid-argument` `reason: "unknown-field"` (§5); en particular un `sessionId` en el cuerpo **nunca** se usa como identidad y se rechaza.
|
|
289
|
+
|
|
290
|
+
Respuesta `200`: el bloque `session` de §6.1, más `changed: true|false` y `revision` resultante.
|
|
291
|
+
|
|
292
|
+
Comportamiento determinista (control de concurrencia optimista):
|
|
293
|
+
|
|
294
|
+
1. El backend lee la selección actual de la sesión (`session_scope`, campo `revision`). `GET /session` ya la expone en `selection.revision`; si no hay selección, el cliente envía `0`.
|
|
295
|
+
2. **Coincide** (`expectedRevision === revision actual`): se aplica la selección con una única sentencia condicional (`UPDATE … WHERE session_id = ? AND revision = ?`). Si el proyecto no cambia, `changed:false` y la revisión **no** sube (idempotente). Si cambia, `changed:true`, `revision = revisión + 1`, auditoría `session.reselect` con el `revision` nuevo.
|
|
296
|
+
3. **No coincide**: no se escribe **nada**; respuesta `409 revision-conflict` con `details: { "expectedRevision": <enviada>, "currentRevision": <actual> }`. El cliente debe releer `GET /session` y reintentar; la UI no reintenta sola.
|
|
297
|
+
4. **Carrera entre dos pestañas**: la condición `revision = ?` es atómica dentro de `BEGIN IMMEDIATE`; exactamente una gana y la otra recibe `409 revision-conflict`. Nunca «la última gana» en silencio.
|
|
298
|
+
5. `expectedRevision` no entero, negativo o ausente → `400 invalid-argument` (`reason: "invalid-field"`).
|
|
299
|
+
6. `selectedBy` es siempre `human`/`host`; la API no acepta `actor`, `sessionId`, `source` ni `scope` en el cuerpo. `[IMPLEMENTED]` (`registerSelection` rechaza `selectedBy` distinto de `human|host`) + `[PROPOSED]` (condición de revisión).
|
|
300
|
+
|
|
301
|
+
Invalidaciones (sin escritura): `session-expired` (409), `scope-forbidden` con `reason` de invalidación (403), `scope-forbidden` `reason: "project-unavailable"` si el proyecto no existe, está archivado o no es candidato (una sola respuesta, C-07), `invalid-argument` si el id no es `prj_…`.
|
|
302
|
+
|
|
303
|
+
> **Estado de implementación (ACP-01, `pa/1.1.0`): CERRADO.** `POST /lifecode-rag/pa/selection` aplica
|
|
304
|
+
> este contrato con estas precisiones, todas medidas por `tests/selection-cas.test.mjs`:
|
|
305
|
+
>
|
|
306
|
+
> - **Alcance de la selección:** una fila por perfil (`pa_selection`, `selection_key='profile'`), no por
|
|
307
|
+
> `session_scope`. El motivo es PA01: el host no ofrece identidad de sesión al plugin (§3.2), y atar la
|
|
308
|
+
> selección del panel a un `SessionId` sin autenticar sería inventar identidad. Consecuencia buscada:
|
|
309
|
+
> la selección **sobrevive al cierre de sesión y al reinicio**.
|
|
310
|
+
> - **Petición:** `{ "projectId": "prj_…", "expectedRevision": 0 }`, esquema estricto; cualquier otra clave
|
|
311
|
+
> → `400 invalid-argument` (`unknown-field`).
|
|
312
|
+
> - **Respuesta 200:** `{ changed, revision, selection: {projectId, projectName, revision, source, selectedBy,
|
|
313
|
+
> principal, selectedAt, updatedAt}, project: {id, name} }`. No se implementa `GET /session`, así que la
|
|
314
|
+
> respuesta devuelve el bloque de selección ya resuelto en vez de la sesión completa.
|
|
315
|
+
> - **Conflicto:** `409 revision-conflict` con `details: { reason: "revision-mismatch", expectedRevision,
|
|
316
|
+
> currentRevision, current: { projectId, projectName, revision } }`. No se escribe nada.
|
|
317
|
+
> - **Proyecto inválido o ajeno:** `403 project-not-authorized` (el código `scope-forbidden` de §7 no existe
|
|
318
|
+
> en `RAG_CODES` de este build; `project-not-authorized` es el que ya usa toda la API PA para ese hecho).
|
|
319
|
+
> - **Idempotencia:** mismo proyecto con la revisión vigente → `changed:false` y la revisión **no** sube.
|
|
320
|
+
> - **Carrera entre dos paneles:** `BEGIN IMMEDIATE` + condición de revisión; exactamente uno confirma y el
|
|
321
|
+
> otro recibe `409`, que el panel traduce en recarga de la revisión vigente y aviso, sin reintento automático.
|
|
322
|
+
> - **Auditoría:** cada cambio confirmado escribe `selection.select` / `selection.reselect` en la cadena del
|
|
323
|
+
> registro (`actor:'human'`, `detail.revision`, `detail.previous`, `detail.principal`).
|
|
324
|
+
>
|
|
325
|
+
> El reducer del panel no adelanta la revisión: `select-project` en modo API deja `pending:'selection'` y sólo
|
|
326
|
+
> pinta el cambio al recibir `selection-ok` con la revisión confirmada (`tests/client.test.mjs`).
|
|
327
|
+
|
|
328
|
+
### 6.11 `GET /history` (ACP-02)
|
|
329
|
+
|
|
330
|
+
Historial de auditoría del **proyecto activo**, de sólo lectura. Implementado en `pa/1.2.0`.
|
|
331
|
+
|
|
332
|
+
```json
|
|
333
|
+
{
|
|
334
|
+
"scope": { "id": "prj_…", "kind": "prj", "name": "…" },
|
|
335
|
+
"total": 141,
|
|
336
|
+
"entries": [
|
|
337
|
+
{
|
|
338
|
+
"seq": 141, "at": 1795043069763, "actor": "automation",
|
|
339
|
+
"tool": "lifecode_rag_sync", "action": "sync.run",
|
|
340
|
+
"target": "prj_…", "outcome": "ok",
|
|
341
|
+
"hash": "5bc176a33fa5cc11", "details": null
|
|
342
|
+
}
|
|
343
|
+
],
|
|
344
|
+
"nextCursor": "91",
|
|
345
|
+
"integrity": { "ok": true, "count": 141 }
|
|
346
|
+
}
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
| Regla | Detalle |
|
|
350
|
+
|---|---|
|
|
351
|
+
| Ámbito | Estructural: las filas salen del almacén **del proyecto activo** (`audit` del scope store). No hay `where` de ámbito que se pueda olvidar, porque otro proyecto es otro fichero |
|
|
352
|
+
| Paginación | `?limit=` (1–200, por defecto 50) y `?cursor=<seq>` (devuelve entradas con `seq` menor). `nextCursor` es `null` al final |
|
|
353
|
+
| Procedencia | `seq`, `hash` (16 hex) y `integrity` (verificación de la cadena completa con el código del plugin) |
|
|
354
|
+
| Redacción | `target` se relativiza a las raíces autorizadas (nunca ruta absoluta); `details` pasa por **lista blanca**: `sourceId, chunks, bytes, code, revision, replace, embedding, skipped`. Nada de `sessions`, `paths` ni mensajes de error con trayectorias |
|
|
355
|
+
| Autenticación | La misma compuerta del host que el resto (§3, PA01); sin credencial → `401` |
|
|
356
|
+
| Errores | `400 invalid-argument` (cursor o límite inválidos, parámetro no declarado), `403 project-not-authorized`, `503 authorization-unavailable` |
|
|
357
|
+
|
|
358
|
+
> Si la API no puede servirlo, el panel mantiene el estado «no disponible» y **no** pinta filas: un historial
|
|
359
|
+
> vacío y un historial inaccesible se distinguen (`entries: []` con `integrity.ok` frente a error de
|
|
360
|
+
> transporte).
|
|
361
|
+
|
|
362
|
+
### 6.12 Administración de proyectos (`pa/1.3.0`, ACP-07 F3)
|
|
363
|
+
|
|
364
|
+
Ocho rutas nuevas, todas bajo la compuerta del host (§3.2) y todas **fuera** del alcance de las siete
|
|
365
|
+
herramientas del modelo: un agente no puede invocarlas, y sin compuerta no existen.
|
|
366
|
+
|
|
367
|
+
| Método | Ruta | Cuerpo / query | Respuesta | Efecto |
|
|
368
|
+
|---|---|---|---|---|
|
|
369
|
+
| POST | `/pa/projects` | `{name, path?}` | 201 `{created, project, integrity}` | Crea proyecto; con `path`, también su primera raíz |
|
|
370
|
+
| PATCH | `/pa/projects` | `{id, name}` | 200 `{changed, project, integrity}` | Renombra |
|
|
371
|
+
| POST | `/pa/projects/archive` | `{id}` | 200 `{changed, project, selection, selectionChange, integrity}` | Archiva y resuelve la selección en la misma transacción |
|
|
372
|
+
| POST | `/pa/projects/restore` | `{id}` | 200 `{changed, project, integrity}` | Restaura conservando identidad y raíces |
|
|
373
|
+
| POST | `/pa/roots` | `{projectId, path}` | 201 `{root, project, integrity}` | Añade una raíz autorizada |
|
|
374
|
+
| POST | `/pa/roots/remove` | `{rootId}` o `{projectId, path}`, `allowEmpty?` | 200 `{removed, project, integrity}` | Retira la raíz; **no borra archivos ni fuentes** |
|
|
375
|
+
| GET | `/pa/candidates` | `?path=` (o `?project=`) `&maxDepth=` | 200 `{root, total, candidates[], skipped, truncated}` | Descubre; **no escribe nada** |
|
|
376
|
+
| POST | `/pa/projects/register` | `{path, name?}` | 201/200 `{created, registeredRoot, project, integrity}` | Registra un candidato de forma explícita |
|
|
377
|
+
|
|
378
|
+
Reglas que no se relajan:
|
|
379
|
+
|
|
380
|
+
- **Compuerta primero.** Sin `authorize` en el handler, las ocho rutas responden
|
|
381
|
+
`503 authorization-unavailable`; con la compuerta negando, `401 unauthenticated` o `403`. Es la misma
|
|
382
|
+
compuerta que protege el resto de la API, no una segunda puerta.
|
|
383
|
+
- **Nada se borra físicamente.** No hay ruta que elimine proyectos, raíces, archivos ni almacenes RAG.
|
|
384
|
+
Archivar es lógico (`status='archived'`, `archived_at`); quitar una raíz borra su fila del registro y
|
|
385
|
+
deja `root.remove` en la auditoría, y el directorio sigue donde estaba.
|
|
386
|
+
- **Ninguna ruta abre `scopes/<id>/rag.sqlite3`.** El almacén de fuentes sólo lo abren `/snapshot`,
|
|
387
|
+
`/history`, `/search` y `/context`. Probado con el hash del almacén antes y después de archivar.
|
|
388
|
+
- **Descubrir y registrar son actos separados (D-02, D-05).** `/candidates` sólo lee y exige raíz
|
|
389
|
+
autorizada para lectura; `/projects/register` es la escritura, con su asiento de auditoría.
|
|
390
|
+
- **Toda escritura es una transacción con asiento.** `project.create`, `project.update`,
|
|
391
|
+
`project.archive`, `project.restore`, `root.add`, `root.remove` y `project.discover` van a
|
|
392
|
+
`audit_registry` con la cadena encadenada por hash; cada respuesta de escritura devuelve
|
|
393
|
+
`integrity: verifyRegistryAudit(db)`.
|
|
394
|
+
- **Campos estrictos.** Se acepta la lista exacta por método; cualquier otra clave produce
|
|
395
|
+
`400 invalid-argument` con `reason: "unknown-field"`. Igual con la query.
|
|
396
|
+
- **Un proyecto archivado deja de ser consultable por id**: `403 project-not-authorized`. Sigue
|
|
397
|
+
apareciendo en `archived` del snapshot, que es desde donde se restaura.
|
|
398
|
+
|
|
399
|
+
`GET /pa/snapshot` crece de forma **aditiva** (§6.2): se añaden `archived[]` y
|
|
400
|
+
`capabilities{projects, roots, discovery}`, y cada elemento de `projects` gana `status`, `total` y
|
|
401
|
+
`selectable`. Las claves anteriores (`id`, `name`, `roots`, `authorized`, `current`) no cambian de
|
|
402
|
+
significado. Cuando no queda ningún proyecto activo (todos archivados), el snapshot responde 200 con
|
|
403
|
+
`project: null` y las listas, en vez de un error: es el retrato que permite restaurar.
|
|
404
|
+
|
|
405
|
+
### 6.3 `GET /projects`
|
|
406
|
+
|
|
407
|
+
Devuelve **sólo** proyectos seleccionables por esa sesión:
|
|
408
|
+
|
|
409
|
+
1. el proyecto actualmente seleccionado (si existe y está activo);
|
|
410
|
+
2. proyectos activos con alguna raíz autorizada que contenga el `cwd` de la sesión.
|
|
411
|
+
|
|
412
|
+
No devuelve el catálogo global. `[PROPOSED]`, construido sobre `matchingProjects` (`[IMPLEMENTED]` pero privada en `lib/resolve.mjs`) y `listRoots` + `pathKeyFor` (`[IMPLEMENTED]` `lib/registry.mjs`). Ver GAP-04.
|
|
413
|
+
|
|
414
|
+
```json
|
|
415
|
+
{ "projects": [ { "id": "prj_…", "name": "…", "current": true, "rootCount": 2 } ], "cwdKnown": true }
|
|
416
|
+
```
|
|
417
|
+
|
|
418
|
+
Si el `cwd` no está disponible y no hay selección, la lista es vacía y `GET /session` informa `unresolvable`. No se auto-selecciona nada.
|
|
419
|
+
|
|
420
|
+
### 6.4 `GET /libraries`
|
|
421
|
+
|
|
422
|
+
```json
|
|
423
|
+
{
|
|
424
|
+
"libraries": [
|
|
425
|
+
{ "id": "lib_…", "name": "…", "permission": "read",
|
|
426
|
+
"grantedAt": 1763…, "grantedBy": "human | host",
|
|
427
|
+
"store": "present | missing | corrupt | unreadable | migrating",
|
|
428
|
+
"roots": 1 }
|
|
429
|
+
],
|
|
430
|
+
"effectiveScopes": 3
|
|
431
|
+
}
|
|
432
|
+
```
|
|
433
|
+
|
|
434
|
+
Sólo aparecen grants abiertos (`revoked_at IS NULL`) de bibliotecas activas, tal como los calcula `effectiveScopes`/`effectiveScopesForProject` (`[IMPLEMENTED]`). Una biblioteca revocada **desaparece** de la lista; su revocación se explica en `/session` (`invalidReason`). No se enumeran bibliotecas globales. El estado del almacén se obtiene con la capa `library-state` (`[IMPLEMENTED]`) **después** de que el ámbito esté autorizado.
|
|
435
|
+
|
|
436
|
+
### 6.5 `GET /sources?limit=50&offset=0&collection=&tag=`
|
|
437
|
+
|
|
438
|
+
Proyecto activo **exclusivamente** (misma semántica que `lifecode_rag_list`, `[IMPLEMENTED]` `listProject`).
|
|
439
|
+
|
|
440
|
+
```json
|
|
441
|
+
{
|
|
442
|
+
"total": 121, "limit": 50, "offset": 0,
|
|
443
|
+
"rows": [ { "id": "src_…", "uri": "docs/x.md", "title": "X", "collection": "default",
|
|
444
|
+
"bytes": 1234, "chunks": 8, "updatedAt": 1763…,
|
|
445
|
+
"indexedAt": 1763…, "mime": "text/markdown" } ]
|
|
446
|
+
}
|
|
447
|
+
```
|
|
448
|
+
|
|
449
|
+
`rows[]` base = `listSourceRows` `[EXISTENTE]` (`id, uri, title, collection, bytes, chunks, updatedAt`); `mime`, `indexedAt`, `sha256`, `charCount` están en la tabla `sources` pero no se proyectan hoy → `[DERIVABLE]`.
|
|
450
|
+
|
|
451
|
+
### 6.6 `GET /sources/:id`
|
|
452
|
+
|
|
453
|
+
Proyecto activo únicamente; el `:id` se resuelve con `getSource(db, ref)` (acepta **id o URI**, `[IMPLEMENTED]` `lib/search.mjs:282`). Si no existe → `404 source-not-found`.
|
|
454
|
+
|
|
455
|
+
```json
|
|
456
|
+
{
|
|
457
|
+
"source": { "id": "…", "uri": "…", "title": "…", "mime": "…", "sha256": "…", "bytes": 0,
|
|
458
|
+
"charCount": 0, "collection": "default", "metadata": {},
|
|
459
|
+
"createdAt": 0, "updatedAt": 0, "indexedAt": 0 },
|
|
460
|
+
"chunks": [ { "ordinal": 0, "heading": "…", "charStart": 0, "charEnd": 0,
|
|
461
|
+
"tokenEst": 0, "text": "…" } ],
|
|
462
|
+
"chunksTotal": 8
|
|
463
|
+
}
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
`source` = fila completa de `sources` `[EXISTENTE]`; `chunks` = filas de `chunks` (`ordinal, heading, char_start, char_end, token_est, text`) `[EXISTENTE]` en tabla, pero no hay hoy una función exportada que liste fragmentos por fuente → `[GAP]` pequeño (ver GAP-05). `text` se recorta al límite de §8.
|
|
467
|
+
|
|
468
|
+
### 6.7 `POST /search`
|
|
469
|
+
|
|
470
|
+
```json
|
|
471
|
+
{ "query": "…", "limit": 8 }
|
|
472
|
+
```
|
|
473
|
+
|
|
474
|
+
Semántica idéntica a `lifecode_rag_search` sobre los ámbitos efectivos (`[IMPLEMENTED]` `searchScopes`), con dos campos añadidos **sólo en la API visual** (no en la herramienta): `scopeKind` y `scopeName`, para que la UI muestre procedencia.
|
|
475
|
+
|
|
476
|
+
```json
|
|
477
|
+
{
|
|
478
|
+
"mode": "hybrid | lexical | vector",
|
|
479
|
+
"elapsedMs": 42,
|
|
480
|
+
"results": [
|
|
481
|
+
{ "chunkKey": "…", "sourceId": "…", "uri": "…", "title": "…", "heading": "…",
|
|
482
|
+
"ordinal": 3, "rrf": 0.031, "snippet": "…",
|
|
483
|
+
"scopeId": "prj_…|lib_…", "scopeKind": "prj|lib", "scopeName": "…" }
|
|
484
|
+
],
|
|
485
|
+
"scopes": [ { "id": "prj_…", "kind": "prj", "name": "…", "results": 7 } ]
|
|
486
|
+
}
|
|
487
|
+
```
|
|
488
|
+
|
|
489
|
+
`scopeId`, `scopeKind` y `scopeName` existen **sólo** en la API visual: la herramienta v0.1 los elimina por proyección (`[IMPLEMENTED]` `lib/tools.mjs`) y el motor de búsqueda de un solo almacén no los devuelve. En la implementación actual (`lib/pa-api.mjs`) **se derivan del único ámbito que el handler abre**: el proyecto autorizado. Por eso `scopeKind` es siempre `"prj"` y `scopeName`/`scopeId` son los del proyecto activo; no hay ámbitos de biblioteca que repartir mientras el handler no abra sus almacenes. No existe una función `searchScopes` en este build: no se documenta como dependencia.
|
|
490
|
+
|
|
491
|
+
> **Implementación LE-RAG-11 (laboratorio PA).** `lib/pa-api.mjs` sirve `/search` y `/context`
|
|
492
|
+
> **sólo por POST**; `GET` sobre ellas devuelve `405 method-not-allowed` con `details.allow: ["POST"]`.
|
|
493
|
+
> Como la cabecera de sesión de este contrato está `BLOCKED` (PA01), el proyecto se indica con el
|
|
494
|
+
> parámetro `?project=prj_…` en la query del POST: es el único parámetro admitido en esas rutas y
|
|
495
|
+
> cualquier otro produce `400 invalid-argument` `reason: "unknown-parameter"`.
|
|
496
|
+
>
|
|
497
|
+
> El handler abre únicamente el almacén del proyecto activo, así que **todas** las filas llevan
|
|
498
|
+
> `scopeKind: "prj"`, `scopeId` y `scopeName` del proyecto: no inventa ámbitos de biblioteca.
|
|
499
|
+
> Además de `rrf` (peso de fusión, tal como figura arriba) la respuesta incluye `score` normalizado
|
|
500
|
+
> `0..1`, que es el valor que pinta el panel. `uri` se relativiza contra las raíces autorizadas del
|
|
501
|
+
> proyecto: nunca sale una ruta absoluta del disco.
|
|
502
|
+
>
|
|
503
|
+
> Validación estricta del cuerpo (todas las ramas responden `400 invalid-argument` **sin ejecutar** la
|
|
504
|
+
> operación; el error nunca se degrada a una lista de resultados vacía):
|
|
505
|
+
>
|
|
506
|
+
> | Caso | `details` |
|
|
507
|
+
> |---|---|
|
|
508
|
+
> | cuerpo vacío | `reason: "missing-body"` |
|
|
509
|
+
> | JSON inválido | `reason: "invalid-json"` |
|
|
510
|
+
> | cuerpo que no es objeto | `reason: "invalid-body"` |
|
|
511
|
+
> | campo no declarado | `reason: "unknown-field"`, `fields: ["…"]` |
|
|
512
|
+
> | falta `query` | `reason: "missing-field"`, `field: "query"` |
|
|
513
|
+
> | `query` no es texto, vacío o sólo espacios | `reason: "invalid-field"`, `field: "query"` |
|
|
514
|
+
> | `query` de más de 512 caracteres | `reason: "query-too-long"`, `field: "query"`, `max: 512` |
|
|
515
|
+
> | `limit` no entero o menor que 1 | `reason: "invalid-field"`, `field: "limit"` |
|
|
516
|
+
> | `limit` mayor que 50 | `reason: "limit-too-large"`, `field: "limit"`, `max: 50` |
|
|
517
|
+
> | `budgetTokens` no entero o menor que 1 | `reason: "invalid-field"`, `field: "budgetTokens"` |
|
|
518
|
+
> | parámetro de query no declarado | `reason: "unknown-parameter"`, `parameters: ["…"]` |
|
|
519
|
+
>
|
|
520
|
+
> Cuerpo mayor de 1 MiB → `413 too-large`. Las consultas se ejecutan con `record: false`: una lectura
|
|
521
|
+
> no añade eventos de auditoría.
|
|
522
|
+
|
|
523
|
+
### 6.8 `POST /context`
|
|
524
|
+
|
|
525
|
+
```json
|
|
526
|
+
{ "query": "…", "budgetTokens": 2000 }
|
|
527
|
+
```
|
|
528
|
+
|
|
529
|
+
Salida idéntica a `lifecode_rag_context` (`text`, `citations` con los 9 campos de v0.1, `tokens`, `truncated`, `considered`) **más** `scopes` (procedencia por ámbito) y `elapsedMs`. `[IMPLEMENTED]` `contextScopes` + `assembleContextAsync`; los campos de cita se toman de `CONTRATO-v0.1.md` sin cambios.
|
|
530
|
+
|
|
531
|
+
> **Implementación LE-RAG-11.** Mismo transporte que `/search`: sólo POST con `{"query","budgetTokens"}`,
|
|
532
|
+
> proyecto por `?project=prj_…`, `GET` → `405`. El `budgetTokens` omitido usa el valor de configuración
|
|
533
|
+
> (`config.context.budgetTokens`, 2000 por defecto). `text` es el texto que se serviría al modelo;
|
|
534
|
+
> `citations[].uri` se relativiza contra las raíces autorizadas (sin rutas absolutas) y cada cita añade
|
|
535
|
+
> `chunkKey`, `sourceId` y `score` a los campos de v0.1. `assembleContextAsync` devuelve `tokens`,
|
|
536
|
+
> `truncated` y `considered` reales: la implementación anterior publicaba `tokensEstimate` (siempre
|
|
537
|
+
> `null`) y omitía `text`, lo que se corrige aquí.
|
|
538
|
+
|
|
539
|
+
Si alguna biblioteca concedida tiene almacén ilegible, la operación **falla cerrada** con `scope-store-unavailable`/`scope-store-corrupt` (comportamiento PA4-F, `[IMPLEMENTED]`): no se devuelve contexto parcial con datos de otros ámbitos.
|
|
540
|
+
|
|
541
|
+
### 6.9 `GET /diagnostics`
|
|
542
|
+
|
|
543
|
+
Información mínima y redactada:
|
|
544
|
+
|
|
545
|
+
```json
|
|
546
|
+
{
|
|
547
|
+
"session": { "id": "…", "profileKey": "…", "state": "active" },
|
|
548
|
+
"selection": { "projectId": "…", "source": "explicit", "revision": 3 },
|
|
549
|
+
"scopes": [ { "kind": "prj|lib", "id": "…", "name": "…", "store": "present|missing|corrupt", "verified": true } ],
|
|
550
|
+
"grants": [ { "libraryId": "…", "permission": "read", "grantedAt": 0, "state": "open" } ],
|
|
551
|
+
"integrity": { "registry": "ok|denied", "stores": "ok|degraded", "auditHead": 0 },
|
|
552
|
+
"versions": { "plugin": "1.0.0", "contract": "0.1.0", "api": "pa-ui/0.1.0-draft", "host": "0.2.2-rc.5" },
|
|
553
|
+
"health": { "status": "ok|degraded", "checks": [ { "id": "registry", "ok": true } ] }
|
|
554
|
+
}
|
|
555
|
+
```
|
|
556
|
+
|
|
557
|
+
Reglas: `roots` se muestran como **conteo** y, si hace falta un nombre, el último segmento; nunca rutas absolutas de proyectos ni de otros perfiles. `registryIntegrity`/`verifyAuditChain` (`[IMPLEMENTED]`) pueden ejecutarse en modo lectura y devolver `ok/denied` sin detalle interno. Sin credenciales, sin `home` del host, sin rutas de almacén, sin SQL, sin trazas.
|
|
558
|
+
|
|
559
|
+
### 6.10 `GET /health`
|
|
560
|
+
|
|
561
|
+
```json
|
|
562
|
+
{ "api": "pa-ui/0.1.0-draft", "contract": "0.1.0", "status": "ok|degraded", "registry": "ok|unavailable", "legacy": false }
|
|
563
|
+
```
|
|
564
|
+
|
|
565
|
+
`legacy:false` documenta explícitamente que **no** se está sirviendo la API v0.2 ni su almacén.
|
|
566
|
+
|
|
567
|
+
---
|
|
568
|
+
|
|
569
|
+
## 7. Errores
|
|
570
|
+
|
|
571
|
+
Se reutilizan los códigos de `lib/errors.mjs` (`[IMPLEMENTED]`), mapeados a HTTP y a un mensaje seguro para la persona. La UI nunca muestra `details` crudos: muestra `message` + un `hint` fijo por código.
|
|
572
|
+
|
|
573
|
+
| Código RAG | HTTP | Significado | Mensaje visible (ES) | Nunca revelar |
|
|
574
|
+
|---|---|---|---|---|
|
|
575
|
+
| `unauthenticated` `[IMPLEMENTED · PA01]` | 401 | el host no reconoce el peer: sin cookie de GUI o cookie inválida/caducada (se emite **antes** de entrar a la ruta del plugin) | «Vuelve a abrir DeepSeek Harness desde el enlace que imprime `dsh web`.» | si faltaba la cookie, si era inválida o si caducó |
|
|
576
|
+
| `session-invalid` | 401 | cabecera `x-lifecode-rag-session` ausente o mal formada | «No hay una sesión válida para esta ventana.» | patrón interno, id recibido |
|
|
577
|
+
| `session-unavailable` | 409 | no hay agente vivo con ese id (o el id no existe) | «La sesión ya no está activa; recarga la ventana.» | si el id existió alguna vez, existencia de otras sesiones |
|
|
578
|
+
| `session-expired` | 409 | sesión terminada (`expireSession`) | «La sesión terminó; abre una nueva.» | `expires_at` ajeno |
|
|
579
|
+
| `scope-unresolved` | 409 | sin selección y sin cwd resoluble | «Elige un proyecto para esta sesión.» | raíces de otros proyectos |
|
|
580
|
+
| `scope-ambiguous` | 409 | selección y cwd incompatibles, o varias raíces | «El directorio de trabajo no coincide con el proyecto; elige explícitamente.» | candidatos ajenos completos (sólo id/nombre) |
|
|
581
|
+
| `scope-forbidden` | 403 | proyecto archivado, sesión invalidada, ámbito fuera de la instantánea | «No tienes acceso a este proyecto en esta sesión.» | `invalid_reason` interno si es sensible |
|
|
582
|
+
| `scope-too-many` | 409 | >8 ámbitos | «La selección supera el máximo de ámbitos.» | lista de scopes no autorizados |
|
|
583
|
+
| `grant-revoked` | 403 | grant revocado durante la operación | «El acceso a una biblioteca cambió; vuelve a consultar.» | nombre de la biblioteca ajena |
|
|
584
|
+
| `invalid-argument` | 400 | parámetro o campo inválido/desconocido | «La solicitud no es válida.» | valores internos |
|
|
585
|
+
| `revision-conflict` `[IMPLEMENTED · CR-1]` | 409 | `expectedRevision` no coincide con la revisión actual | «Otra pestaña cambió el proyecto; recarga y reintenta.» | revisión de otras sesiones |
|
|
586
|
+
| `forbidden` `[IMPLEMENTED · PA01]` | 403 | la compuerta del host rechaza la petición pese a estar bien formada (trust/`Origin`) | «Esta ventana no está autorizada a leer el panel.» | motivo del rechazo en el host |
|
|
587
|
+
| `authorization-unavailable` `[IMPLEMENTED · PA01]` | 403 / 503 | el host no ofrece `ctx.connection` (403) o la compuerta falló al decidir (503): la API PA queda cerrada | «La autenticación del host no está disponible; el panel está cerrado.» | detalle interno del servicio |
|
|
588
|
+
| `audit-unavailable` `[PROPOSED]` | 503 | no se pudo escribir el evento `ui.read`; la lectura **no** se sirve | «No se pudo registrar el acceso; la operación no se completó.» | detalle del fallo de escritura, SQL, rutas |
|
|
589
|
+
| `source-not-found` | 404 | fuente inexistente en el proyecto | «La fuente no existe en este proyecto.» | si existe en otro proyecto |
|
|
590
|
+
| `store-not-initialized` | 503 | perfil sin registro | «El perfil aún no está inicializado.» | rutas del perfil |
|
|
591
|
+
| `registry-unavailable` | 503 | registro no disponible | «El registro del proyecto no está disponible.» | ruta del registro |
|
|
592
|
+
| `registry-corrupt` | 500 | registro corrupto | «El registro del proyecto está dañado.» | detalle SQL/fichero |
|
|
593
|
+
| `scope-store-unavailable` | 503 | almacén de biblioteca ausente/cargando | «Una biblioteca concedida no está disponible ahora mismo.» (puede incluir `Retry-After`) | rutas |
|
|
594
|
+
| `scope-store-corrupt` | 500 | almacén ilegible | «Una biblioteca concedida está dañada.» | detalle SQLite |
|
|
595
|
+
| `store-busy` | 503 | bloqueo transitorio | «El almacén está ocupado; reintenta.» | rutas |
|
|
596
|
+
| `fts-integrity` | 500 | índice FTS incoherente | «El índice de búsqueda está dañado.» | detalle |
|
|
597
|
+
| `vector-index-incomplete` | 500 | vectores incompletos | «El índice vectorial está incompleto.» | detalle |
|
|
598
|
+
| `too-large` | 413 | petición demasiado grande | «La solicitud es demasiado grande.» | límites internos exactos |
|
|
599
|
+
| `response-too-large` | 500 | la respuesta excedería el tope de 1 MiB y no se sirve | «La respuesta es demasiado grande para servirla.» | tamaño exacto del payload |
|
|
600
|
+
| `approval-required` | 409 | acción destructiva sin aprobación (no aplica a PA-UI-0) | «Esta acción requiere aprobación humana.» | — |
|
|
601
|
+
| `approval-unavailable` | 503 | sin servicio de aprobación | «No se puede pedir aprobación en este entorno.» | — |
|
|
602
|
+
| `egress-denied` | 403 | embedder remoto denegado | «El proveedor de embeddings no está autorizado.» | endpoint del proveedor |
|
|
603
|
+
| `embedding-failed` | 502 | fallo del embedder | «La búsqueda semántica no está disponible.» | mensaje del proveedor |
|
|
604
|
+
| `cancelled` | 499 `[PROPOSED]`/408 | petición abortada | «Consulta cancelada.» | — |
|
|
605
|
+
| `operation-uncertain` | 409 | resultado de escritura incierto | «La operación quedó en estado incierto; revisa el diagnóstico.» | — |
|
|
606
|
+
| `recovery-verification-failed` | 500 | verificación de recuperación fallida | «La recuperación no superó la verificación.» | — |
|
|
607
|
+
| `sync-root-unavailable` | 503 | raíz de sincronización no disponible | «Una raíz del proyecto no está accesible.» | ruta |
|
|
608
|
+
| `internal` | 500 | error no clasificado | «Error interno del servicio RAG.» | stack, SQL, rutas |
|
|
609
|
+
|
|
610
|
+
Reglas transversales: los errores de autorización **se auditan** en el registro (`appendRegistryAudit`, `[IMPLEMENTED]`); los de almacén siguen el contrato de errores PA2 (`[DOCUMENTED]` `docs/PROJECT-AWARE-ERROR-CONTRACT.md`). La API visual nunca responde con `200 { ok:false }`: usa el sobre de error con el status indicado. La diferenciación de errores no puede servir para enumerar: proyecto inexistente y proyecto no autorizado comparten respuesta (`403 scope-forbidden`, `reason: "project-unavailable"`); sesión desconocida y agente caído comparten `409 session-unavailable`.
|
|
611
|
+
|
|
612
|
+
### 7.1 Auditoría de lecturas: `ui.read` (PA03, revisado en PA-UI-0.2)
|
|
613
|
+
|
|
614
|
+
**Regla única (append-only estricto):** cada lectura auditada escribe **exactamente un evento nuevo e inmutable** en la cadena de auditoría del registro (`appendRegistryAudit`, hash-chain existente, `[IMPLEMENTED]`), sin cambios de esquema (`audit_registry`: `seq, at, actor, session_id, call_id, tool, action, target, outcome, detail`).
|
|
615
|
+
|
|
616
|
+
1. **Un evento por lectura.** No hay actualización de eventos, ni deduplicación, ni contadores que se incrementen después. Un evento escrito **nunca** se modifica (ni `detail`, ni `outcome`, ni `repeat`); la cadena `prev_hash`/`hash` lo impide por construcción.
|
|
617
|
+
2. **No existe `detail.repeat`.** Se retiró del contrato en PA-UI-0.2 (PA02) porque exigía mutar un evento ya escrito.
|
|
618
|
+
3. **Lectura auditada** = toda petición HTTP a una ruta de datos de §5 (todas salvo `/health`) que devuelva o modifique datos de sesión/proyecto, con independencia de que sea la primera, un refresco manual o un polling automático. Cada petición cuenta como una lectura y genera su fila.
|
|
619
|
+
4. **Polling y refrescos.** El control de volumen es de diseño de cliente, no de auditoría: el panel no hace polling si no está visible (WORKSPACE-UX §5), y el mínimo es 30 s. Ese polling, cuando ocurre, **sí** genera un evento por petición; no se suprime ni se agrega. Una petición repetida en el mismo segundo produce dos filas distintas, con `seq`, `at` y `call_id` propios.
|
|
620
|
+
5. **Reintentos.** Un reintento del cliente es una lectura nueva y genera su propio evento. No se reutiliza el `call_id` de la petición fallida.
|
|
621
|
+
6. **Fail-closed.** Si no se puede escribir el evento, la lectura **no** se sirve y se responde `503 audit-unavailable`. Excepción: `/health` (no auditado, no devuelve datos de sesión). No se sirve «sin dejar rastro».
|
|
622
|
+
7. **Sin esquema nuevo.** Se usa la tabla y la cadena existentes; no se añaden triggers, tablas, columnas ni ficheros.
|
|
623
|
+
|
|
624
|
+
| Campo del evento | Valor |
|
|
625
|
+
|---|---|
|
|
626
|
+
| `at` | epoch ms del inicio de la operación (no del final) |
|
|
627
|
+
| `actor` | `human` — **origen de la solicitud** (canal de interfaz operado por una persona), **no** una identidad autenticada. El host no prueba identidad humana (§3.2); el registro no debe leerse como «persona autenticada». La UI nunca escribe `model`: las acciones del modelo van por las herramientas v0.1 y conservan su propio `actor`. |
|
|
628
|
+
| `session_id` | **identidad efectiva** = `agent.id` resuelto (§3.3), nunca el string crudo de la cabecera |
|
|
629
|
+
| `call_id` | `correlationId` (UUID v4 generado por el servidor, devuelto en `x-lifecode-rag-request`) |
|
|
630
|
+
| `tool` | `lifecode_rag_ui` (constante; distingue el canal visual de las herramientas v0.1) |
|
|
631
|
+
| `action` | `ui.read` |
|
|
632
|
+
| `target` | operación lógica, una de: `session`, `projects`, `libraries`, `sources`, `source`, `search`, `context`, `selection` (sólo en lectura previa), `diagnostics` |
|
|
633
|
+
| `outcome` | `ok` \| `denied` \| `failed` |
|
|
634
|
+
| `detail` | JSON **redactado**: `{ "operation": "<target>", "status": <HTTP>, "durationMs": <entero>, "projectId": "prj_…" \| null, "scopeCount": <entero> }` — máximo 512 bytes serializados. Lista cerrada: cualquier otra clave es un fallo de contrato. |
|
|
635
|
+
|
|
636
|
+
**Exclusiones obligatorias del evento** (ni en `target`, ni en `detail`, ni en mensajes): texto de consulta (`query`), texto recuperado, snippets, títulos, URIs, nombres de fichero, rutas absolutas, cabeceras, cookies/tokens, cuerpos de petición o respuesta, `sessionId` de otras sesiones, ids de ámbitos (`scopeId`/`libraryId`), errores SQL y stacks. `projectId` sí se registra: es el proyecto activo de la propia sesión auditada.
|
|
637
|
+
|
|
638
|
+
**Redacción:** cualquier valor que no sea uno de los campos enumerados no se escribe; no hay «modo verboso». Un fallo al construir `detail` no impide el evento: se escribe `detail: {}` y `outcome` correcto.
|
|
639
|
+
|
|
640
|
+
**Por qué no hay deduplicación (decisión PA02):** la deduplicación con `repeat` exigía reescribir una fila ya encadenada, lo que contradice el carácter append-only del registro y permitía que un evento cambiara después de ser leído como prueba. Se elimina por completo: la auditoría gana en integridad y la contención de volumen se resuelve en el cliente (polling sólo con panel visible, 30 s).
|
|
641
|
+
|
|
642
|
+
**Append-only:** el evento se escribe **después** de la operación y **antes** de enviar el cuerpo; si el cliente aborta después, el evento queda con el `status` que se iba a enviar (`ok` para 2xx). La escritura es una transacción corta (`BEGIN IMMEDIATE`) sobre el registro, nunca sobre el almacén de ámbito.
|
|
643
|
+
|
|
644
|
+
---
|
|
645
|
+
|
|
646
|
+
## 8. Paginación, límites y rendimiento
|
|
647
|
+
|
|
648
|
+
Clasificación de PA05. Ningún valor de esta tabla se presenta como rendimiento medido si no lo está:
|
|
649
|
+
|
|
650
|
+
- **CONTRATO** — fijado por `CONTRATO-v0.1.md` o por el esquema ya implementado; cambiarlo rompería v0.1.
|
|
651
|
+
- **MEDIDO (motor)** — medido en el banco de eficiencia local, **no** sobre HTTP.
|
|
652
|
+
- **PROVISIONAL** — valor de diseño sin medición; se revisa con el banco de PA-UI-1.
|
|
653
|
+
- **PENDIENTE HOST** — depende de una capacidad o del comportamiento del host; no verificable en PA-UI-0.
|
|
654
|
+
- **DECISIÓN UX** — política de producto/interfaz, no límite técnico.
|
|
655
|
+
|
|
656
|
+
| Recurso | Valor | Clase | Origen / nota |
|
|
657
|
+
|---|---|---|---|
|
|
658
|
+
| Fuentes por página | 50 por defecto; máximo 200 | CONTRATO | `listSources` (50) y `listProject` (200) `[IMPLEMENTED]`; por encima, `400 invalid-argument` — en la API PA lo aplica `queryParams` de `lib/pa-api.mjs` (`reason: "limit-too-large"`) |
|
|
659
|
+
| Desplazamiento de fuentes | entero ≥ 0, acotado por `total` | CONTRATO | `LIMIT ? OFFSET ?` `[IMPLEMENTED]` |
|
|
660
|
+
| Resultados de búsqueda | 8 por defecto; máximo 50 | CONTRATO | `CONTRATO-v0.1.md`; `limit: 51` → `400` |
|
|
661
|
+
| Presupuesto de contexto | 2000 tokens por defecto | CONTRATO | `config.context` `[IMPLEMENTED]` |
|
|
662
|
+
| Fragmentos por fuente | 200 por defecto; máximo 500 | 200 CONTRATO / 500 PROVISIONAL | `getAcross` (200) `[IMPLEMENTED]`; 500 es diseño |
|
|
663
|
+
| Texto por fragmento | 1200 caracteres en detalle | CONTRATO | tamaño de chunk de v0.1 |
|
|
664
|
+
| `snippet` en búsqueda | 240 caracteres | PROVISIONAL | sin medición; recorte de presentación |
|
|
665
|
+
| Consulta | 512 caracteres | PROVISIONAL | no hay límite medido del motor; por encima, `400` (nunca recorte silencioso) |
|
|
666
|
+
| Respuesta | 1 MiB | PROVISIONAL | cuerpos mayores → `413 too-large` |
|
|
667
|
+
| Tiempo por operación | 10 s | PROVISIONAL | el motor mide 32–45 ms en banco local (`[IMPLEMENTED]` `tests/efficiency.test.mjs`), **no** el canal HTTP |
|
|
668
|
+
| Polling de la UI | 30 s mínimo; sólo con panel visible | DECISIÓN UX | §7.1 + WORKSPACE-UX §5; no hay dedupe de auditoría |
|
|
669
|
+
| Tamaño de cuerpo de petición | 1 MiB | PROVISIONAL | §5 |
|
|
670
|
+
|
|
671
|
+
Paginación: **offset** es suficiente y compatible con el modelo actual. No se introduce cursor en PA-UI-1. La búsqueda no pagina (el motor devuelve top-k; ampliar `limit` es la vía, acotada a 50) — decisión D-UI-06 confirmada.
|
|
672
|
+
|
|
673
|
+
**Rendimiento no medido:** PA-UI-0 no ejecutó el canal HTTP. Los criterios J-01/J-02 (p95) son objetivos de PA-UI-1, no resultados. Cualquier cifra de latencia HTTP citada en otro documento sin evidencia de PA-UI-1 es una previsión, no una medida.
|
|
674
|
+
|
|
675
|
+
---
|
|
676
|
+
|
|
677
|
+
## 9. Seguridad
|
|
678
|
+
|
|
679
|
+
### 9.1 Requisitos no negociables
|
|
680
|
+
|
|
681
|
+
1. **Autenticación del peer = la del host** (cookie de GUI, principal `owner`). La sesión es direccionamiento, no credencial (§3.2–3.3). La API **no** afirma en ningún sitio que autentica una sesión. `[VERIFIED HOST]` + `[IMPLEMENTED · PA01]`: el adaptador llama a `ctx.connection.requestRejection` y `admit` en **cada** petición, antes de resolver la ruta; sin `ctx.connection` niega (`503 authorization-unavailable`). Medido: `tests/pa-auth.test.mjs` (8 casos) y `tests/host-adapter.test.mjs`.
|
|
682
|
+
2. Resolución de sesión/proyecto antes de cualquier dato (§4).
|
|
683
|
+
3. Grants validados en cada operación; revalidación antes de devolver (`ctx.checkpoint`). `[IMPLEMENTED]`
|
|
684
|
+
4. Apertura de almacenes sólo vía `ctx.open`. `[IMPLEMENTED]`
|
|
685
|
+
5. Cierre garantizado en `finally`. `[IMPLEMENTED]`
|
|
686
|
+
6. Sin fallback al almacén heredado: la API visual no consulta `rag.sqlite3`. `[IMPLEMENTED]` (hoy ni existe)
|
|
687
|
+
7. Sin acceso global: `GET /projects` acotado a cwd/selección; `/sources` y `/sources/:id` sólo proyecto.
|
|
688
|
+
8. Bibliotecas en lectura; la API visual no expone ninguna escritura salvo `/selection`.
|
|
689
|
+
9. Denegación por defecto: cabecera ausente → `401 session-invalid`; sin selección → `409`; biblioteca sin grant → no listada.
|
|
690
|
+
10. **Escritura mínima estricta:** `POST /selection` acepta **exactamente** `projectId` + `expectedRevision`; cualquier otro campo → `400 invalid-argument` (rechazo, no ignorar). `[PROPOSED]` (PA02)
|
|
691
|
+
11. Redacción de diagnóstico (§6.9) y de auditoría (§7.1).
|
|
692
|
+
12. Render seguro en cliente: todo texto va como nodo de texto (nunca `innerHTML` con datos del motor).
|
|
693
|
+
13. **Auditoría de lectura obligatoria y fail-closed:** si no se puede escribir `ui.read`, no se sirve el dato (`503 audit-unavailable`). `[PROPOSED]` (PA03)
|
|
694
|
+
14. **Sin CORS** y `x-lifecode-rag: 1` obligatoria en `POST`; `Origin`/`Host` loopback verificados.
|
|
695
|
+
15. **Sin enumeración por errores:** proyecto inexistente ≡ no autorizado; sesión desconocida ≡ agente caído (§7).
|
|
696
|
+
|
|
697
|
+
### 9.2 Matriz de amenazas
|
|
698
|
+
|
|
699
|
+
| # | Amenaza | Vector | Control | Estado |
|
|
700
|
+
|---|---|---|---|---|
|
|
701
|
+
| T1 | Suplantar otra sesión enviando su `sessionId` | cabecera HTTP | lookup en agentes vivos + loopback + token del GUI + auditoría por lectura | **NO MITIGABLE por el plugin** → BLOCKED (D-UI-03) |
|
|
702
|
+
| T2 | Pedir un ámbito ajeno en query/body | `?scope=`, `?project=` | parámetros inexistentes; sólo `projectId` en `/selection`, validado contra candidatos | diseñado |
|
|
703
|
+
| T3 | Acceso cruzado entre proyectos | refs de fuente | `getSource` se ejecuta **dentro** del almacén del proyecto autorizado; ids de otro proyecto no resuelven | diseñado |
|
|
704
|
+
| T4 | Biblioteca sin grant | `/libraries`, search | sólo `effectiveScopes`; store ni se abre | implementado (PA3) |
|
|
705
|
+
| T5 | Fallback al almacén v0.2 | ruta API | prefijo distinto; `legacy:false`; sin lectura de `rag.sqlite3` | implementado |
|
|
706
|
+
| T6 | Fuga de datos en error | mensajes 5xx | catálogo cerrado de mensajes; `details` nunca se envían | diseñado |
|
|
707
|
+
| T7 | Exposición de rutas absolutas | `/diagnostics` | sólo conteos/final de ruta | diseñado |
|
|
708
|
+
| T8 | XSS en títulos/snippets | contenido indexado | render como texto; CSP del GUI | diseñado (PA-UI-1) |
|
|
709
|
+
| T9 | CSRF desde una página local | POST | cabecera `x-lifecode-rag`, JSON, Origin loopback, token del host | diseñado |
|
|
710
|
+
| T10 | Inyección SQL | parámetros | consultas ya parametrizadas; la API no concatena SQL | implementado (motor) |
|
|
711
|
+
| T11 | DoS por consultas costosas | search loop | límites §8 + `maxVectorScan` del motor | implementado (motor) |
|
|
712
|
+
| T12 | Selección automática por el modelo | UI | `/selection` exige actor humano; ninguna herramienta llama a la API | diseñado |
|
|
713
|
+
| T13 | Proceso local con la cookie del GUI se hace pasar por `owner` y direcciona otra sesión | cookie/token del host | Ninguno disponible en el plugin; es el modelo del host (owner no se comprueba); mismo riesgo que las APIs de sesión nativas | **BLOCKED (host)** — D-UI-03 |
|
|
714
|
+
| T14 | Inundación de la auditoría por polling | UI | `/health` no auditado; polling acotado en cliente (30 s, sólo visible); una fila **inmutable** por petición (sin dedupe) | diseñado (PA03/PA02) |
|
|
715
|
+
| T15 | Enumeración de sesiones/proyectos por diferencias de error | respuestas | `403 project-unavailable` único; `409 session-unavailable` único; sin distinguir existencia | diseñado (PA04) |
|
|
716
|
+
| T16 | Fuga de datos a través de la auditoría | cadena de auditoría | `detail` con lista cerrada de campos, máximo 512 B, sin texto/URIs/rutas | diseñado (PA03) |
|
|
717
|
+
| T17 | Inyección por campos desconocidos en el cuerpo | `POST` | esquema estricto → `400 invalid-argument`; nunca se usa `sessionId` del cuerpo | diseñado (PA02) |
|
|
718
|
+
|
|
719
|
+
---
|
|
720
|
+
|
|
721
|
+
## 10. Compatibilidad
|
|
722
|
+
|
|
723
|
+
- **Herramientas v0.1:** sin cambios de nombre, esquema, semántica ni salida. La API visual es un contrato separado (`pa-ui/0.1.0-draft`).
|
|
724
|
+
- **`CONTRATO-v0.1.md`:** intacto (SHA-256 arriba).
|
|
725
|
+
- **API v0.2 (`/lifecode-rag/api`):** no se reutiliza; sigue montándose sólo si existe el almacén heredado, para quien lo tenga (`[IMPLEMENTED]` `index.js`).
|
|
726
|
+
- **Almacenes:** sólo bajo la raíz de datos RAG (`$DSH_HOME/lifecode-rag` o `LIFECODE_RAG_ROOT`): `profiles/<perfil>/registry.sqlite3` y `profiles/<perfil>/scopes/<scope>/rag.sqlite3`; sin almacén legado como respaldo.
|
|
727
|
+
- **Host:** contrato de slots/servicios de DSH 0.2.2-rc.5; cualquier versión fuera de `>=0.2.2-rc.3 <0.3.0` queda fuera del contrato (`engines.dsh` del plugin).
|
|
728
|
+
|
|
729
|
+
---
|
|
730
|
+
|
|
731
|
+
## 11. Decisiones y estado tras PA-UI-0.1 (actualizado en PA-UI-0.2)
|
|
732
|
+
|
|
733
|
+
| Id | Decisión | Estado | Resolución |
|
|
734
|
+
|---|---|---|---|
|
|
735
|
+
| D-UI-01 | Nombre y prefijo de la API: `/lifecode-rag/ui/api` | **CONFIRMADA** | Prefijo distinto de la API v0.2; sin cambios. |
|
|
736
|
+
| D-UI-02 | Transporte de identidad | **BLOCKED** (antes «cabecera + lookup») | La cabecera es direccionamiento; el host no autentica sesiones. No se declara resuelta (§3.2–3.4). |
|
|
737
|
+
| D-UI-03 | Riesgo residual de suplantación local | **BLOCKED / PENDING HUMAN DECISION** | **No otorgada.** Requiere decisión humana explícita e independiente. Documentar la limitación no es aceptarla (§3.5). |
|
|
738
|
+
| D-UI-04 | `expectedRevision` en selección | **RESUELTA DOCUMENTALMENTE** | Contrato §6.2: obligatoria, `409 revision-conflict`, sin escritura en conflicto. Implementación pendiente (GAP-09). |
|
|
739
|
+
| D-UI-05 | Candidatos = cwd ∪ actual | **CONFIRMADA** | Sin descubrimiento global; `/projects` acotado. |
|
|
740
|
+
| D-UI-06 | Sin paginación de búsqueda; offset en fuentes | **CONFIRMADA** | §8. |
|
|
741
|
+
| D-UI-07 | Auditar lecturas `ui.read` | **RESUELTA DOCUMENTALMENTE** (revisada en PA-UI-0.2) | §7.1: un evento inmutable por lectura, sin dedupe ni `repeat`, `actor` de origen, fail-closed. Implementación pendiente (GAP-07). |
|
|
742
|
+
| D-UI-08 | Diagnóstico con rutas redactadas | **CONFIRMADA** | §6.9: conteo + último segmento; nunca ruta absoluta. |
|
|
743
|
+
| D-UI-09 | Cifras 512 / 1 MiB / 10 s / 240 / 500 | **CLASIFICADAS** | §8: PROVISIONAL salvo las marcadas CONTRATO; ninguna medida HTTP. |
|
|
744
|
+
| D-UI-10 | `session-unavailable` como código propio, 409 | **RESUELTA** | §7: `409 session-unavailable` (antes 401). |
|
|
745
|
+
| D-UI-11 | Vía alternativa de mitigación por aislamiento topológico | **NOT DEMONSTRATED** (nueva en PA-UI-0.2) | §3.6: criterios TI-1…TI-7; no es autenticación; no se ha ejecutado ninguna prueba. |
|
|
746
|
+
|
|
747
|
+
**Resultado global de PA-UI-0.1: `BLOCKED`** por PA01/D-UI-03. PA-UI-1 sigue sin autorización. PA-UI-0.2 no cambia el resultado: ordena la auditoría (PA02), fija `actor` (PA03), unifica GAP-20 como `OPEN / DOCUMENTED HOST LIMITATION` y añade la ruta topológica como mitigación **no demostrada**.
|
|
748
|
+
|
|
749
|
+
---
|
|
750
|
+
|
|
751
|
+
## 12. Trazabilidad de este documento
|
|
752
|
+
|
|
753
|
+
- Código inspeccionado: `lib/exec-context.mjs`, `lib/resolve.mjs`, `lib/sessions.mjs`, `lib/registry-schema.mjs`, `lib/schema.mjs`, `lib/errors.mjs`, `lib/scope-ops.mjs`, `lib/tools.mjs`, `lib/server.mjs`, `lib/readmodel.mjs`, `lib/search.mjs`, `lib/session-identity.mjs`, `index.js`, `client.js`, `package.json`.
|
|
754
|
+
- Host inspeccionado en vivo (sólo lectura): `agents`, `connection`, `webServer`, `workingDirectory`, `approval`, `tools`; slots `sidebar.panellist`, `main`, `conversation.session.header.actions`; servicios de cliente `sessions`, `slots`, `locale`.
|
|
755
|
+
- Fuentes del host leídas en `app.asar` (sólo lectura, PA-UI-0.1): `@deepseek-ai/dsh-client-connection/src/browser-auth.ts`, `src/api-request-trust.ts`, `src/peer.ts`, `README.md`; `@deepseek-ai/dsh-api-remote-access/README.md`; `@deepseek-ai/dsh-api-session-controller/src/index.ts`; `@deepseek-ai/dsh-authorization/src/index.ts` (flujos de obtención de credenciales OAuth/token, no identidad de sesión).
|
|
756
|
+
- Diagnóstico previo: `eval/pa3/evidence/D-UI-RAG-01-REPORT.md` (UI actual = BLOCKED; herramientas = VERIFIED HOST).
|
|
757
|
+
- Este documento **no** afirma que la UI exista: la UI Project-Aware está **NO IMPLEMENTADA** (`[GAP]`).
|
|
758
|
+
|
|
759
|
+
---
|
|
760
|
+
|
|
761
|
+
## 13. Registro de revisión PA-UI-0.1 (2026-11-18)
|
|
762
|
+
|
|
763
|
+
Cambios de esta revisión, exclusivamente documentales:
|
|
764
|
+
|
|
765
|
+
1. **§3 reescrita.** Separación explícita entre *autenticación del peer* (host, `owner`) y *direccionamiento de sesión* (cabecera). Añadidas las tablas de evidencia del host (§3.2) y de alternativas evaluadas (§3.4). PA01 → `BLOCKED`.
|
|
766
|
+
2. **§4** incorpora la auditoría de lectura y la cabecera `x-lifecode-rag-request`; el agente vivo pasa a `409 session-unavailable`.
|
|
767
|
+
3. **§5** añade rechazo estricto de campos/parámetros desconocidos, correlación y cuerpo máximo.
|
|
768
|
+
4. **§6.2** convierte `expectedRevision` en obligatoria con `409 revision-conflict` y escritura condicional atómica (PA02).
|
|
769
|
+
5. **§7** distingue `unauthenticated` (host), `session-invalid` (401), `session-unavailable`/`session-expired` (409), y añade `revision-conflict` y `audit-unavailable`; §7.1 define `ui.read` completo (PA03).
|
|
770
|
+
6. **§8** clasifica cada límite en CONTRATO / MEDIDO / PROVISIONAL / DECISIÓN UX (PA05).
|
|
771
|
+
7. **§9** elimina la afirmación de que el host transporta identidad; matriz con T13–T17.
|
|
772
|
+
8. **§11** registra el estado de D-UI-01…10.
|
|
773
|
+
|
|
774
|
+
Sin cambios en: código (`lib/`, `index.js`, `client.js`), `package.json`, esquemas, endpoints, slots, perfiles, registro, almacenes, `CONTRATO-v0.1.md`, `skill-compiler/`, `_audit/`, `lifecode-skill-center/`, `MEMORY.md`, `AGENTS.md`. Sin instalación, sin reinicio, sin `node --test` raíz, sin operaciones Git de escritura.
|
|
775
|
+
|
|
776
|
+
**Resultado:** `BLOCKED` (PA01/D-UI-03). Los demás puntos, resueltos documentalmente. Detalle y matrices en `docs/PA-UI-0.1-REVIEW.md`.
|
|
777
|
+
|
|
778
|
+
---
|
|
779
|
+
|
|
780
|
+
## 14. Registro de revisión PA-UI-0.2 (2026-11-18)
|
|
781
|
+
|
|
782
|
+
Cambios, exclusivamente documentales:
|
|
783
|
+
|
|
784
|
+
1. **§7.1 reescrita (PA02).** Append-only estricto: un evento **nuevo e inmutable** por lectura; se elimina la deduplicación de 5 s y el campo `detail.repeat` porque exigían mutar filas ya encadenadas. Se define «lectura auditada» (toda petición a rutas de datos, incluido polling y refresco) y se traslada la contención de volumen al cliente (sin polling si el panel no está visible; mínimo 30 s). Fail-closed se mantiene.
|
|
785
|
+
2. **§7.1 `actor` (PA03).** `actor = human` para todo `ui.read`, definido como **origen del canal** (persona operando el panel), no como identidad autenticada; se prohíbe escribir `model` por la UI. Se distingue origen de solicitud de autenticación de identidad.
|
|
786
|
+
3. **§3.4/§3.5 (GAP-20).** La limitación del host pasa a `OPEN / DOCUMENTED HOST LIMITATION`; se elimina el lenguaje de «riesgo aceptado»; D-UI-03 queda `BLOCKED / PENDING HUMAN DECISION` y **no otorgada**.
|
|
787
|
+
4. **§3.6 nueva (ruta topológica).** Criterios TI-1…TI-7 para una mitigación por aislamiento; se declara `NOT DEMONSTRATED`, se distingue expresamente de la autenticación de sesión y no se ejecutó ninguna prueba.
|
|
788
|
+
5. **§11** añade D-UI-11 y actualiza D-UI-03/D-UI-07.
|
|
789
|
+
6. **§13** se conserva íntegro como historial.
|
|
790
|
+
|
|
791
|
+
Ver `docs/PA-UI-0.2-REVIEW.md` para la tabla de hallazgos y la verificación.
|
|
792
|
+
|
|
793
|
+
---
|
|
794
|
+
|
|
795
|
+
## 15. Registro de revisión ACP-01 (2026-11-21)
|
|
796
|
+
|
|
797
|
+
Cambios de implementación (con su documentación):
|
|
798
|
+
|
|
799
|
+
1. **PA01 — autenticación del panel (§3, §7, §9.1).** La API PA estaba **abierta**: `webServer.register`
|
|
800
|
+
no pasa por la compuerta del host y `GET /lifecode-rag/pa/health` respondía 200 sin credencial. Ahora
|
|
801
|
+
`createPaHandler` recibe una `authorize` opcional y el adaptador la construye con
|
|
802
|
+
`ctx.connection.requestRejection({headers})` + `admit({headers})`. La compuerta se evalúa **antes** de
|
|
803
|
+
resolver la ruta (una ruta inventada y una real responden lo mismo sin credencial), el principal se toma
|
|
804
|
+
del `Peer` del host (`owner`) y ninguna cabecera del renderer concede identidad. Sin servicio de conexión
|
|
805
|
+
se falla cerrado. Códigos nuevos en `RAG_CODES`: `unauthenticated`, `forbidden`,
|
|
806
|
+
`authorization-unavailable`.
|
|
807
|
+
2. **CR-1 — selección con CAS (§6.2).** Implementada según lo descrito arriba; esquema del registro
|
|
808
|
+
**v2** con tabla aditiva `pa_selection` (`lib/registry-schema.mjs`, `lib/selection.mjs`) y migración
|
|
809
|
+
aditiva dentro de `openRegistry` (un registro v1 se abre, se migra y conserva datos y auditoría).
|
|
810
|
+
3. **Snapshot.** `GET /snapshot` devuelve `selection` (proyección de `pa_selection`), `projects` (los
|
|
811
|
+
proyectos **activos** del perfil con `id`, `name`, `roots`, `authorized` y `current`: es la lista que el
|
|
812
|
+
panel necesita para cambiar de proyecto) y `auth.principal` (sólo el principal del host, nunca
|
|
813
|
+
credenciales). Con varios proyectos y sin selección sigue siendo `403 scope-ambiguous`: no se elige un
|
|
814
|
+
proyecto «por defecto» a la callada.
|
|
815
|
+
El panel pide `?limit=200` (el máximo de §8) para que la lista cargada coincida con el total del perfil;
|
|
816
|
+
si el proyecto tiene más de 200 fuentes, la vista lo declara (`sources.capped`) en vez de presentar la
|
|
817
|
+
página como si fuera el total.
|
|
818
|
+
4. **Versión de la API:** `PA_VERSION = 'pa/1.1.0'` (en ACP-02 sube a `pa/1.2.0` por §6.11).
|
|
819
|
+
5. **Pruebas.** `tests/pa-auth.test.mjs` (8 casos de PA01), `tests/selection-cas.test.mjs` (9 casos de CR-1),
|
|
820
|
+
dos casos de compuerta en `tests/host-adapter.test.mjs`, tres de reducer en `tests/client.test.mjs` y la
|
|
821
|
+
migración v1→v2 en `tests/registry.test.mjs`.
|
|
822
|
+
|
|
823
|
+
Sin cambios en: contratos de las siete herramientas, almacenes de ámbito, DEMO/fixtures, motor de búsqueda,
|
|
824
|
+
embeddings y presupuesto de contexto.
|
|
825
|
+
|
|
826
|
+
---
|
|
827
|
+
|
|
828
|
+
## 16. Registro de revisión ACP-02 (2026-11-22)
|
|
829
|
+
|
|
830
|
+
1. **Catálogo de errores completo y único (`lib/errors.mjs`).** `RAG_CODES` pasa de 34 a 52 códigos: se
|
|
831
|
+
añadieron los 18 que el código lanzaba sin catalogar —entre ellos los de autorización (`scope-forbidden`,
|
|
832
|
+
`grant-revoked`, `session-invalid`, `session-expired`, `project-not-authorized`, `scope-ambiguous`,
|
|
833
|
+
`scope-too-many`, `scope-unresolved`) y los de ruta (`path-escape`, `hardlink-refused`, `root-overlap`,
|
|
834
|
+
`sequence-conflict`, `vector-index-incomplete`, `registry-*`, `scope-store-*`, `sync-root-unavailable`)—.
|
|
835
|
+
El catálogo y el mapa `HTTP_STATUS` son el mismo conjunto (biyección probada) y **un solo mapa** alimenta
|
|
836
|
+
las dos APIs: `pa-api` y el servidor heredado (`LEGACY_HTTP_OVERRIDES` declara las tres diferencias de la
|
|
837
|
+
v0.2). Un `RagError` con código no catalogado conserva el código (`catalogued:false`) en vez de convertirse
|
|
838
|
+
en `internal` en silencio.
|
|
839
|
+
2. **Clasificación explícita de seguridad.** `SECURITY_CODES` (decisiones: siempre 4xx, probado que nunca
|
|
840
|
+
5xx) y `FAIL_CLOSED_CODES` (`approval-unavailable`, `authorization-unavailable`: 503 porque el fallo es del
|
|
841
|
+
servicio, no una decisión). Invariante probada por status: todo `401`/`403` del catálogo está clasificado.
|
|
842
|
+
3. **`GET /history` (§6.11)** implementado con paginación, ámbito estructural y redacción; el panel estrena la
|
|
843
|
+
pestaña **Historial** con cadena verificada en lugar del «no disponible».
|
|
844
|
+
4. **Pruebas:** `tests/error-codes.test.mjs` (8 casos, recorren el fuente) y `tests/pa-history.test.mjs`
|
|
845
|
+
(5 casos). Total del proyecto: **448**.
|
|
846
|
+
|
|
847
|
+
---
|
|
848
|
+
|
|
849
|
+
## 17. Registro de revisión ACP-07 F3 (2026-11-22)
|
|
850
|
+
|
|
851
|
+
1. **`pa/1.3.0`.** Se añaden las ocho rutas de administración de §6.12 y el snapshot crece de forma
|
|
852
|
+
aditiva. `pa/1.2.0` sigue siendo un subconjunto válido: ningún consumidor de 1.2.0 pierde una clave ni
|
|
853
|
+
cambia su significado, y las pruebas de compatibilidad de `tests/pa-api.test.mjs` siguen en verde sin
|
|
854
|
+
tocarlas.
|
|
855
|
+
2. **La administración no es una herramienta.** Las siete tools del modelo no cambian de permisos y
|
|
856
|
+
ninguna ruta administrativa es alcanzable desde ellas. Sin compuerta del host, las rutas responden
|
|
857
|
+
`503 authorization-unavailable`: no hay versión abierta.
|
|
858
|
+
3. **Archivar respeta la resolución atómica de F1.** La ruta llama a `archiveProjectWithSelection`, que
|
|
859
|
+
mueve o retira la selección en la misma transacción; `archiveProject` sola sigue negándose.
|
|
860
|
+
4. **Agujero cerrado en el camino:** `projectView` seleccionaba proyectos sin filtrar por estado, así que
|
|
861
|
+
un proyecto archivado podía seguir consultándose por id. Ahora sólo se resuelven proyectos activos.
|
|
862
|
+
5. **Pruebas:** `tests/pa-admin.test.mjs` (10 casos: compuerta, creación con y sin raíz, renombrado,
|
|
863
|
+
archivado con selección y sin tocar el almacén, restauración, raíces con solape y borrado lógico,
|
|
864
|
+
candidatos sin escritura, registro idempotente, snapshot sin proyecto activo y compatibilidad de 1.2.0).
|
|
865
|
+
|
|
866
|
+
---
|
|
867
|
+
|
|
868
|
+
## 18. Registro de revisión ACP-07 F4 (2026-11-22)
|
|
869
|
+
|
|
870
|
+
1. **Interfaz de administración (§6.12) en el panel.** Dos secciones nuevas —**Proyectos** y
|
|
871
|
+
**Candidatos**— y las acciones de F3 conectadas: crear (con raíz opcional), renombrar, archivar,
|
|
872
|
+
restaurar, añadir y quitar raíces, descubrir y registrar un candidato.
|
|
873
|
+
2. **Descubrimiento bajo demanda.** Abrir la sección Candidatos no explora nada: sólo el botón
|
|
874
|
+
«Buscar candidatos» lanza `GET /candidates`. Probado en `tests/client.test.mjs` (navegar no
|
|
875
|
+
provoca ni una petición).
|
|
876
|
+
3. **Registro como acto humano.** El botón «Registrar» de una fila llama a `POST /projects/register` con
|
|
877
|
+
esa ruta. No hay registro automático en ninguna ruta del panel, y el descubrimiento sigue sin escribir.
|
|
878
|
+
4. **`scope-unresolved` deja de ser un callejón.** Cuando el panel no puede hidratar porque el proyecto
|
|
879
|
+
no está registrado (F2), muestra el código, la explicación, el botón **Ir a Candidatos** y la
|
|
880
|
+
alternativa de la CLI. Antes se pintaban fixtures bajo un rótulo de error, sin salida.
|
|
881
|
+
5. **Campo aditivo `roots` en el snapshot.** El recuento por proyecto no permitía retirar una raíz
|
|
882
|
+
concreta. Se añade `roots: [{scopeId, id, path, state}]`, dentro de `pa/1.3.0` y sin tocar ninguna
|
|
883
|
+
clave existente.
|
|
884
|
+
6. **Archivar y restaurar son reversibles desde la interfaz**, con aviso explícito de que el almacén y
|
|
885
|
+
las fuentes se conservan.
|
|
886
|
+
7. **Evidencia de UI:** seis capturas del panel real (montado con el `client.js` del producto y React del
|
|
887
|
+
host) contra `createPaHandler` sobre un **perfil temporal**, en `_audit/evidence/acp07-f4/`.
|