@designerbyron/lifecode-rag 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +220 -2
  3. package/bin/lifecode-rag.mjs +449 -0
  4. package/client.js +3515 -0
  5. package/cordis.patch.yml +3 -0
  6. package/docs/ARCHITECTURE-v0.2.md +269 -0
  7. package/docs/AUTO-DISCOVERY.md +111 -0
  8. package/docs/AUTOMATION-POLICIES.md +232 -0
  9. package/docs/CONTRATO-v0.1.md +195 -0
  10. package/docs/EMBEDDING-PROVIDERS.md +105 -0
  11. package/docs/OBSERVABILITY.md +241 -0
  12. package/docs/PA-UI-0-API-CONTRACT.md +887 -0
  13. package/docs/PERFORMANCE-BUDGETS.md +118 -0
  14. package/docs/PROJECT-AWARE-ARCHITECTURE.md +580 -0
  15. package/docs/PROJECT-AWARE-DATA-CONTRACT.md +411 -0
  16. package/docs/PROJECT-AWARE-ERROR-CONTRACT.md +112 -0
  17. package/docs/PROJECT-AWARE-SESSION-CONTRACT.md +120 -0
  18. package/docs/WORKSPACE-API.md +239 -0
  19. package/icon.svg +7 -0
  20. package/index.js +198 -0
  21. package/lib/audit-export.mjs +70 -0
  22. package/lib/audit.mjs +120 -0
  23. package/lib/auto-context.mjs +322 -0
  24. package/lib/automation.mjs +214 -0
  25. package/lib/chunk.mjs +100 -0
  26. package/lib/config-resolve.mjs +119 -0
  27. package/lib/context.mjs +150 -0
  28. package/lib/conversation-events.mjs +145 -0
  29. package/lib/db.mjs +309 -0
  30. package/lib/diagnose.mjs +197 -0
  31. package/lib/discovery.mjs +402 -0
  32. package/lib/doctor.mjs +82 -0
  33. package/lib/embed.mjs +96 -0
  34. package/lib/embedders.mjs +103 -0
  35. package/lib/errors.mjs +231 -0
  36. package/lib/exec-context.mjs +238 -0
  37. package/lib/extract.mjs +260 -0
  38. package/lib/harness-workspaces.mjs +85 -0
  39. package/lib/hash.mjs +34 -0
  40. package/lib/ingest.mjs +239 -0
  41. package/lib/inputs.mjs +67 -0
  42. package/lib/library-state.mjs +252 -0
  43. package/lib/maintenance.mjs +113 -0
  44. package/lib/metrics.mjs +164 -0
  45. package/lib/migrate.mjs +373 -0
  46. package/lib/operations.mjs +132 -0
  47. package/lib/pa-api.mjs +946 -0
  48. package/lib/paths.mjs +345 -0
  49. package/lib/policy.mjs +125 -0
  50. package/lib/profile.mjs +128 -0
  51. package/lib/readmodel.mjs +159 -0
  52. package/lib/recovery.mjs +557 -0
  53. package/lib/registry-schema.mjs +206 -0
  54. package/lib/registry.mjs +606 -0
  55. package/lib/resolve.mjs +318 -0
  56. package/lib/retention.mjs +143 -0
  57. package/lib/revocation.mjs +124 -0
  58. package/lib/roots-structure.mjs +224 -0
  59. package/lib/schema.mjs +173 -0
  60. package/lib/scope-ops.mjs +379 -0
  61. package/lib/scope-stores.mjs +128 -0
  62. package/lib/search.mjs +345 -0
  63. package/lib/selection.mjs +225 -0
  64. package/lib/server.mjs +340 -0
  65. package/lib/session-identity.mjs +51 -0
  66. package/lib/sessions.mjs +343 -0
  67. package/lib/sync-scheduler.mjs +354 -0
  68. package/lib/sync.mjs +755 -0
  69. package/lib/tags.mjs +45 -0
  70. package/lib/tools.mjs +364 -0
  71. package/lib/trusted-roots.mjs +149 -0
  72. package/lib/worker-context.mjs +22 -0
  73. package/package.json +67 -5
@@ -0,0 +1,318 @@
1
+ /**
2
+ * Resolución de ámbitos (PA2.4/PA2.6): determinista y fail-closed.
3
+ *
4
+ * Orden del contrato de sesión:
5
+ * 1. identidad estable del host (atada al perfil),
6
+ * 2. selección explícita persistida,
7
+ * 3. si no hay selección, `cwd` contra raíces autorizadas de proyectos activos,
8
+ * 4. exactamente una coincidencia; cero → `scope-unresolved`, varias → `scope-ambiguous`.
9
+ *
10
+ * No hay proyecto por defecto, ni «el último», ni «el primero». Una selección explícita
11
+ * incompatible con el `cwd` no se corrige sola: se rechaza como ambigua.
12
+ */
13
+
14
+ import { RagError } from './errors.mjs';
15
+ import { appendRegistryAudit, getProject, pathKeyFor } from './registry.mjs';
16
+ import { findProjectBoundary } from './discovery.mjs';
17
+ import { normalizeWorkspace, openProjectForCwd, openProjectForSession } from './harness-workspaces.mjs';
18
+ import { assertSessionId } from './session-identity.mjs';
19
+ import { effectiveScopes, getSession } from './sessions.mjs';
20
+ import { trustedRootFor } from './trusted-roots.mjs';
21
+
22
+ function deny(db, { sessionId, identity, code, message, details, now }) {
23
+ try {
24
+ appendRegistryAudit(db, {
25
+ at: now,
26
+ actor: 'host',
27
+ sessionId: sessionId ?? identity?.sessionId ?? null,
28
+ action: 'scope.resolve',
29
+ target: details?.project_id ?? details?.cwd ?? 'scope',
30
+ outcome: 'denied',
31
+ detail: JSON.stringify({ code, ...details }),
32
+ });
33
+ } catch {
34
+ // si la auditoría falla, el rechazo sigue siendo un rechazo
35
+ }
36
+ throw new RagError(code, message, { details });
37
+ }
38
+
39
+ function insideRoot(cwdKey, rootKey) {
40
+ if (!cwdKey || !rootKey) return false;
41
+ if (cwdKey === rootKey) return true;
42
+ const prefix = rootKey.endsWith('/') ? rootKey : `${rootKey}/`;
43
+ return cwdKey.startsWith(prefix);
44
+ }
45
+
46
+ function matchingProjects(db, cwdKey) {
47
+ const rows = db.prepare(`SELECT p.id AS project_id, p.name AS project_name, r.path, r.path_key
48
+ FROM roots r JOIN projects p ON p.id = r.scope_id
49
+ WHERE r.scope_kind='prj' AND r.state='authorized' AND p.status='active'
50
+ ORDER BY r.path`).all();
51
+ return rows.filter((row) => insideRoot(cwdKey, row.path_key));
52
+ }
53
+
54
+ /**
55
+ * Con raíces anidadas (un proyecto dentro del directorio de otro) gana la raíz más específica:
56
+ * se descarta toda coincidencia cuyo directorio contenga a otra coincidencia distinta. Si tras
57
+ * podar quedan dos proyectos hermanos, la coincidencia sigue siendo ambigua.
58
+ */
59
+ function mostSpecific(matches) {
60
+ return matches.filter((row) => !matches.some((other) => (
61
+ other.project_id !== row.project_id
62
+ && other.path_key !== row.path_key
63
+ && other.path_key.startsWith(`${row.path_key}/`)
64
+ )));
65
+ }
66
+
67
+ /**
68
+ * Averigua a qué proyecto apunta el `cwd` **sin escribir nada** (ACP-07 F2, decisión D-02).
69
+ *
70
+ * Antes esta función registraba el proyecto (`registerDiscoveredProject`). Eso hacía que un simple
71
+ * uso del agente creara filas en el registro y difuminaba la diferencia entre candidato y proyecto
72
+ * registrado. Ahora sólo informa: si el proyecto no está registrado, el llamador devuelve
73
+ * `scope-unresolved` con la acción y el comando para registrarlo.
74
+ *
75
+ * @returns {{boundary: null} | {denied: object} | {boundary: object, projectId: string|null}}
76
+ */
77
+ function probeCwdProject(db, { cwd, sessionId, openProjects }) {
78
+ const cwdKey = typeof cwd === 'string' && cwd.trim() !== '' ? pathKeyFor(cwd) : null;
79
+ const open = openProjectForCwd(openProjects, cwdKey)
80
+ ?? openProjectForSession(openProjects, sessionId);
81
+
82
+ let boundary = null;
83
+ if (open) {
84
+ boundary = { path: open.path, name: open.title, type: 'harness-workspace', indicators: [] };
85
+ } else {
86
+ const trust = trustedRootFor(db, cwdKey);
87
+ if (!trust || trust.readAuthorization !== true) return { boundary: null };
88
+ try {
89
+ boundary = findProjectBoundary(cwd, { withinPath: trust.path });
90
+ } catch {
91
+ return { boundary: null };
92
+ }
93
+ if (!boundary) return { boundary: null };
94
+ }
95
+
96
+ const boundaryKey = pathKeyFor(boundary.path);
97
+ const authorization = trustedRootFor(db, boundaryKey);
98
+ if (!authorization || authorization.readAuthorization !== true) {
99
+ return {
100
+ denied: {
101
+ code: 'scope-unresolved',
102
+ message: 'el proyecto abierto en Harness no está autorizado para lectura',
103
+ details: {
104
+ session_id: sessionId,
105
+ cwd: cwd ?? null,
106
+ reason: 'project-not-authorized',
107
+ project: { id: open?.id ?? null, path: open?.path ?? boundary.path, title: boundary.name },
108
+ command: `node bin/lifecode-rag.mjs trust add --path "${open?.path ?? boundary.path}"`,
109
+ },
110
+ },
111
+ };
112
+ }
113
+
114
+ // Si el proyecto ya está registrado (su raíz existe), se resuelve como siempre: aquí no hay nada
115
+ // que crear ni que autorizar de nuevo.
116
+ const registered = db.prepare(`SELECT scope_id FROM roots
117
+ WHERE scope_kind = 'prj' AND path_key = ? LIMIT 1`).get(boundaryKey);
118
+ return { boundary, projectId: registered?.scope_id ?? null };
119
+ }
120
+
121
+ function scopesOf(db, identity, expectedProfileKey) {
122
+ return effectiveScopes(db, { identity, expectedProfileKey });
123
+ }
124
+
125
+ /**
126
+ * Resuelve el ámbito de una sesión. Devuelve la selección efectiva sin abrir almacenes de ámbito
127
+ * (eso corresponde a PA3) y sin persistir una selección derivada de `cwd`.
128
+ */
129
+ export function resolveScope(db, {
130
+ identity, expectedProfileKey, cwd = null, openProjects = [], now = Date.now(),
131
+ } = {}) {
132
+ if (!identity || typeof identity !== 'object') {
133
+ throw new RagError('session-invalid', 'falta la identidad de sesión', { details: { reason: 'missing-identity' } });
134
+ }
135
+ const sessionId = assertSessionId(identity.sessionId);
136
+ const cwdKey = typeof cwd === 'string' && cwd.trim() !== '' ? pathKeyFor(cwd) : null;
137
+ // Se normaliza en la frontera: cualquier llamante puede pasar la forma cruda del host.
138
+ const open = (Array.isArray(openProjects) ? openProjects : [])
139
+ .map((entry) => normalizeWorkspace(entry))
140
+ .filter(Boolean);
141
+
142
+ if (identity.profileKey !== expectedProfileKey) {
143
+ deny(db, {
144
+ sessionId, identity, code: 'session-invalid',
145
+ message: 'la sesión pertenece a otro perfil',
146
+ details: { reason: 'profile-mismatch' }, now,
147
+ });
148
+ }
149
+
150
+ const session = getSession(db, sessionId);
151
+
152
+ if (session) {
153
+ if (session.state === 'expired') {
154
+ // Una sesión terminada también es una denegación: si no se audita, la cadena miente por omisión.
155
+ deny(db, {
156
+ sessionId, identity, code: 'session-expired',
157
+ message: 'la sesión está terminada',
158
+ details: { session_id: sessionId, reason: 'session-expired', expires_at: session.expires_at }, now,
159
+ });
160
+ }
161
+ if (session.state === 'invalidated') {
162
+ deny(db, {
163
+ sessionId, identity, code: 'scope-forbidden',
164
+ message: 'la selección de la sesión fue invalidada',
165
+ details: { session_id: sessionId, reason: session.invalid_reason }, now,
166
+ });
167
+ }
168
+ const project = getProject(db, session.project_id);
169
+ if (!project || project.status !== 'active') {
170
+ deny(db, {
171
+ sessionId, identity, code: 'scope-forbidden',
172
+ message: 'el proyecto seleccionado no está activo',
173
+ details: { session_id: sessionId, project_id: session.project_id, reason: 'project-archived' }, now,
174
+ });
175
+ }
176
+ if (cwdKey) {
177
+ const matches = mostSpecific(matchingProjects(db, cwdKey));
178
+ const projects = new Set(matches.map((row) => row.project_id));
179
+ if (projects.size > 1 || (projects.size === 1 && !projects.has(session.project_id))) {
180
+ deny(db, {
181
+ sessionId, identity, code: 'scope-ambiguous',
182
+ message: 'el directorio de trabajo no corresponde a la selección explícita',
183
+ details: {
184
+ session_id: sessionId,
185
+ selected_project_id: session.project_id,
186
+ candidates: matches.map((row) => ({ project_id: row.project_id, path: row.path })),
187
+ }, now,
188
+ });
189
+ }
190
+ }
191
+ const effective = scopesOf(db, identity, expectedProfileKey);
192
+ succeed(db, { sessionId, projectId: effective.project.id, source: 'explicit', effective, now });
193
+ return resultOf(sessionId, 'explicit', effective);
194
+ }
195
+
196
+ if (!cwdKey) {
197
+ deny(db, {
198
+ sessionId, identity, code: 'scope-unresolved',
199
+ message: 'la sesión no tiene selección y no hay directorio de trabajo verificable',
200
+ details: { session_id: sessionId, cwd: null }, now,
201
+ });
202
+ }
203
+ let matches = matchingProjects(db, cwdKey);
204
+ if (matches.length === 0) {
205
+ const probe = probeCwdProject(db, { cwd, sessionId, openProjects: open });
206
+ if (probe.denied) {
207
+ deny(db, { sessionId, identity, ...probe.denied, now });
208
+ }
209
+ // Proyecto identificado y ya registrado: el `cwd` puede ser su carpeta contenedora, así que se
210
+ // resuelve por id (no es una coincidencia por prefijo).
211
+ if (probe.projectId) {
212
+ const effective = effectiveScopesForProject(db, probe.projectId);
213
+ succeed(db, { sessionId, projectId: probe.projectId, source: 'cwd', effective, now });
214
+ return resultOf(sessionId, 'cwd', effective);
215
+ }
216
+ // Proyecto identificado pero NO registrado: no se registra solo (D-02). Se devuelve el acto
217
+ // explícito que la persona debe realizar, con su comando.
218
+ if (probe.boundary) {
219
+ deny(db, {
220
+ sessionId, identity, code: 'scope-unresolved',
221
+ message: 'el proyecto no está registrado en este perfil',
222
+ details: {
223
+ session_id: sessionId,
224
+ cwd: cwd ?? null,
225
+ reason: 'project-not-registered',
226
+ action: 'register-project',
227
+ command: `node bin/lifecode-rag.mjs discover register --path "${probe.boundary.path}"`,
228
+ project: {
229
+ path: probe.boundary.path,
230
+ title: probe.boundary.name,
231
+ type: probe.boundary.type,
232
+ },
233
+ }, now,
234
+ });
235
+ }
236
+ }
237
+ matches = mostSpecific(matches);
238
+ const projects = new Set(matches.map((row) => row.project_id));
239
+ if (projects.size === 0) {
240
+ deny(db, {
241
+ sessionId, identity, code: 'scope-unresolved',
242
+ message: 'el directorio de trabajo no está dentro de ninguna raíz autorizada',
243
+ details: {
244
+ session_id: sessionId,
245
+ cwd: cwd ?? null,
246
+ open_projects: open.map((project) => ({ id: project.id, path: project.path, title: project.title })),
247
+ }, now,
248
+ });
249
+ }
250
+ if (projects.size > 1) {
251
+ deny(db, {
252
+ sessionId, identity, code: 'scope-ambiguous',
253
+ message: 'el directorio de trabajo coincide con más de un proyecto',
254
+ details: {
255
+ session_id: sessionId,
256
+ candidates: matches.map((row) => ({ project_id: row.project_id, path: row.path })),
257
+ }, now,
258
+ });
259
+ }
260
+ const [match] = matches;
261
+ const effective = effectiveScopesForProject(db, match.project_id);
262
+ succeed(db, { sessionId, projectId: match.project_id, source: 'cwd', effective, now });
263
+ return resultOf(sessionId, 'cwd', effective);
264
+ }
265
+
266
+ function effectiveScopesForProject(db, projectId) {
267
+ const project = getProject(db, projectId);
268
+ if (!project || project.status !== 'active') {
269
+ throw new RagError('scope-forbidden', 'el proyecto no está activo', {
270
+ details: { project_id: projectId, reason: 'project-archived' },
271
+ });
272
+ }
273
+ const libraries = db.prepare(`SELECT l.* FROM grants g
274
+ JOIN libraries l ON l.id = g.library_id
275
+ WHERE g.project_id = ? AND g.revoked_at IS NULL AND l.status = 'active'
276
+ ORDER BY l.name, l.id`).all(projectId);
277
+ const rootsOf = (scopeKind, scopeId) => db.prepare(
278
+ `SELECT id, path FROM roots WHERE scope_kind=? AND scope_id=? AND state='authorized' ORDER BY path`,
279
+ ).all(scopeKind, scopeId);
280
+ const scopes = [
281
+ { kind: 'prj', id: project.id, name: project.name, roots: rootsOf('prj', project.id) },
282
+ ...libraries.map((library) => ({
283
+ kind: 'lib', id: library.id, name: library.name, roots: rootsOf('lib', library.id),
284
+ })),
285
+ ];
286
+ if (scopes.length > 8) {
287
+ throw new RagError('scope-too-many', 'la selección supera el máximo de ámbitos', {
288
+ details: { project_id: projectId, scopes: scopes.map((scope) => scope.id), limit: 8 },
289
+ });
290
+ }
291
+ return { project, scopes, scopeCount: scopes.length, session: null };
292
+ }
293
+
294
+ function succeed(db, { sessionId, projectId, source, effective, now }) {
295
+ appendRegistryAudit(db, {
296
+ at: now,
297
+ actor: 'host',
298
+ sessionId,
299
+ action: 'scope.resolve',
300
+ target: projectId,
301
+ outcome: 'ok',
302
+ detail: JSON.stringify({ project_id: projectId, source, scopes: effective.scopeCount }),
303
+ });
304
+ }
305
+
306
+ function resultOf(sessionId, source, effective) {
307
+ return {
308
+ sessionId,
309
+ projectId: effective.project.id,
310
+ projectName: effective.project.name,
311
+ source,
312
+ revision: effective.session?.revision ?? null,
313
+ scopes: effective.scopes.map((scope) => ({
314
+ kind: scope.kind, id: scope.id, name: scope.name, roots: scope.roots.map((root) => root.path),
315
+ })),
316
+ scopeCount: effective.scopeCount,
317
+ };
318
+ }
@@ -0,0 +1,143 @@
1
+ /**
2
+ * Retención y archivado de metadatos (PA4-G, observación O-PA0-3).
3
+ *
4
+ * Regla de PA4: este módulo **no borra nada**. Planifica y archiva; ejecutar una retención destructiva
5
+ * exige una política humana aprobada que todavía no existe (propuesta en el informe PA4). Por eso no
6
+ * hay `applyRetention()` ni `DELETE`: si en el futuro se autoriza, tendrá que entrar aquí y pasar por
7
+ * revisión, no colarse desde otro módulo.
8
+ *
9
+ * Qué es retenible y qué no:
10
+ * - `session_scope` expiradas o invalidadas: metadatos operativos, sin valor probatorio propio; su
11
+ * rastro histórico ya vive en `audit_registry` (`session.terminate`, `session.invalidate`).
12
+ * - `operations`/`operation_steps` terminadas: si se archivan, se archivan juntas (los pasos van con
13
+ * su operación) y nunca una fila `started`: esa es una operación interrumpida y se reconcilia, no
14
+ * se borra.
15
+ * - `audit_registry` y la `audit` de cada almacén: **no se borran ni se compactan**. Son la cadena de
16
+ * integridad; archivarlas es copiar, no sustituir. `exportRegistryAuditSlice` copia un rango
17
+ * verificando la cadena antes de escribir.
18
+ */
19
+
20
+ import { createHash } from 'node:crypto';
21
+ import { writeFileSync } from 'node:fs';
22
+
23
+ import { RagError } from './errors.mjs';
24
+ import { canonicalJson } from './audit.mjs';
25
+ import { appendRegistryAudit, registryAuditHash } from './registry.mjs';
26
+
27
+ /** Días de conservación propuestos. No son política aprobada: son la propuesta del informe PA4. */
28
+ export const RETENTION_PROPOSAL = Object.freeze({
29
+ sessionScopeDays: 90,
30
+ finishedOperationsDays: 180,
31
+ dailyMetricsDays: 400,
32
+ });
33
+
34
+ const DAY_MS = 86_400_000;
35
+
36
+ /** Día UTC `YYYY-MM-DD` de un instante, que es el formato de `metrics_daily.day`. */
37
+ export function dayOf(instant) {
38
+ return new Date(instant).toISOString().slice(0, 10);
39
+ }
40
+
41
+ /**
42
+ * Calcula qué se podría archivar y cuánto ocupa, sin tocar nada. Devuelve también lo que la política
43
+ * **nunca** tocaría, para que la decisión humana se tome con el número completo delante.
44
+ */
45
+ export function planRetention(registryDb, { now = Date.now(), policy = RETENTION_PROPOSAL } = {}) {
46
+ const sessionCutoff = new Date(now - policy.sessionScopeDays * DAY_MS).toISOString();
47
+ const metricsCutoff = dayOf(now - policy.dailyMetricsDays * DAY_MS);
48
+ const count = (sql, ...params) => Number(registryDb.prepare(sql).get(...params)?.n ?? 0);
49
+
50
+ const expiredSessions = count(
51
+ `SELECT COUNT(*) AS n FROM session_scope
52
+ WHERE state IN ('expired','invalidated') AND updated_at < ?`, sessionCutoff,
53
+ );
54
+ const activeSessions = count(`SELECT COUNT(*) AS n FROM session_scope WHERE state = 'active'`);
55
+ const unfinishedOperations = count(`SELECT COUNT(*) AS n FROM operations WHERE state = 'started'`);
56
+ const finishedOperations = count(
57
+ `SELECT COUNT(*) AS n FROM operations WHERE state <> 'started'`,
58
+ );
59
+ const auditEntries = count('SELECT COUNT(*) AS n FROM audit_registry');
60
+ const auditHeadHash = registryDb.prepare(`SELECT value FROM meta WHERE key='audit_head_hash'`).get()?.value ?? null;
61
+
62
+ return {
63
+ policy: { ...policy, approved: false, destructive: false },
64
+ asOf: new Date(now).toISOString(),
65
+ candidates: {
66
+ expiredSessions,
67
+ finishedOperations,
68
+ metricsBefore: metricsCutoff,
69
+ },
70
+ protected: {
71
+ activeSessions,
72
+ unfinishedOperations,
73
+ auditRegistryEntries: auditEntries,
74
+ auditHeadHash,
75
+ note: 'la auditoría no se borra ni se compacta; sólo se copia',
76
+ },
77
+ note: 'plan de sólo lectura: PA4 no elimina ni compacta metadatos sin política humana aprobada',
78
+ };
79
+ }
80
+
81
+ /**
82
+ * Copia un rango de la auditoría del registro a JSONL verificando la cadena antes de escribir.
83
+ * No modifica la base. La cabecera del fichero declara el rango y el hash de cabeza para que la copia
84
+ * sea comprobable por sí misma.
85
+ */
86
+ export function exportRegistryAuditSlice(registryDb, { fromSeq = 1, toSeq = null, path, now = Date.now() } = {}) {
87
+ if (typeof path !== 'string' || path.length === 0) {
88
+ throw new RagError('invalid-argument', 'la exportación necesita una ruta de destino');
89
+ }
90
+ const rows = registryDb.prepare(
91
+ `SELECT seq, at, actor, session_id, action, target, outcome, detail, prev_hash, hash
92
+ FROM audit_registry WHERE seq >= ? AND seq <= COALESCE(?, seq) ORDER BY seq ASC`,
93
+ ).all(Number(fromSeq), toSeq === null ? null : Number(toSeq));
94
+
95
+ let previous = fromSeq > 1
96
+ ? (registryDb.prepare('SELECT hash FROM audit_registry WHERE seq = ?').get(Number(fromSeq) - 1)?.hash ?? null)
97
+ : '0'.repeat(64);
98
+ if (previous === null) {
99
+ throw new RagError('registry-corrupt', 'el rango de auditoría no continúa una cadena conocida', {
100
+ details: { fromSeq },
101
+ });
102
+ }
103
+ const seedHash = previous;
104
+ for (const row of rows) {
105
+ const expected = registryAuditHash(previous, {
106
+ at: row.at, actor: row.actor, sessionId: row.session_id, action: row.action,
107
+ target: row.target, outcome: row.outcome, detail: row.detail,
108
+ });
109
+ if (expected !== row.hash) {
110
+ throw new RagError('registry-corrupt', 'la cadena de auditoría del registro no verifica en el rango exportado', {
111
+ details: { seq: row.seq, expected, actual: row.hash },
112
+ });
113
+ }
114
+ previous = row.hash;
115
+ }
116
+
117
+ const header = canonicalJson({
118
+ kind: 'lifecode-rag/registry-audit-slice',
119
+ exportedAt: new Date(now).toISOString(),
120
+ fromSeq: Number(fromSeq),
121
+ toSeq: rows.length > 0 ? rows.at(-1).seq : Number(fromSeq) - 1,
122
+ previousHash: fromSeq > 1 ? seedHash : null,
123
+ headHash: rows.length > 0 ? rows.at(-1).hash : previous,
124
+ });
125
+ const lines = [header, ...rows.map((row) => canonicalJson(row))];
126
+ const body = `${lines.join('\n')}\n`;
127
+ writeFileSync(path, body, 'utf8');
128
+ const seal = createHash('sha256').update(body, 'utf8').digest('hex');
129
+ writeFileSync(`${path}.sha256`, `${seal} ${path.split(/[\\/]/).pop()}\n`, 'utf8');
130
+
131
+ // La exportación es una acción auditable, pero no destructiva: se deja rastro en el registro.
132
+ appendRegistryAudit(registryDb, {
133
+ at: now,
134
+ actor: 'human',
135
+ sessionId: null,
136
+ action: 'audit.export',
137
+ target: String(fromSeq),
138
+ outcome: 'ok',
139
+ detail: { entries: rows.length, path, seal },
140
+ });
141
+
142
+ return { entries: rows.length, bytes: Buffer.byteLength(body, 'utf8'), sha256: seal, path, fromSeq: Number(fromSeq) };
143
+ }
@@ -0,0 +1,124 @@
1
+ /**
2
+ * Revocación efectiva (PA4-B).
3
+ *
4
+ * PA3 fijaba la autorización al empezar la llamada: una consulta en curso terminaba con los ámbitos
5
+ * que ya había abierto. PA4 añade **puntos de control** que vuelven a leer el registro (sin caché de
6
+ * grants) y una garantía verificable:
7
+ *
8
+ * - Antes de abrir cada ámbito se comprueba que sigue autorizado.
9
+ * - Antes de devolver información al consumidor se comprueba otra vez el conjunto completo.
10
+ * - Si durante la operación se revoca un ámbito que la operación tenía autorizado, la operación
11
+ * **no devuelve resultados** de ningún ámbito: falla con `grant-revoked` y deja constancia en la
12
+ * auditoría del registro. Un resultado reducido no se presenta como exhaustivo (v0.1 no puede
13
+ * expresar `partial`).
14
+ *
15
+ * Latencias y límites, que se documentan en vez de prometerse:
16
+ * - El modelo de ejecución es de un solo hilo por proceso: un cambio hecho por *otra conexión* u otro
17
+ * proceso sólo puede confirmarse entre dos sentencias nuestras. La revocación se detecta como muy
18
+ * tarde en el siguiente punto de control, nunca en mitad de una sentencia SQLite propia.
19
+ * - Una escritura ya confirmada (`COMMIT`) no se revierte: la revocación impide seguir escribiendo y
20
+ * devolver datos, no deshace lo escrito. La atomicidad de una escritura termina en su `COMMIT`.
21
+ * - `grant-revoked` con `reason: 'revoked-during-operation'` significa «autorizado al abrir, no
22
+ * autorizado al devolver»; no hay resultados parciales que entregar.
23
+ */
24
+
25
+ import { RagError } from './errors.mjs';
26
+
27
+ /**
28
+ * Estado de autorización actual, leído de la base del registro. Sin caché: cada llamada ve lo que
29
+ * hay comprometido en ese instante.
30
+ */
31
+ export function currentAuthorization(db, { sessionId, projectId, sessionOptional = false } = {}) {
32
+ const session = db.prepare('SELECT * FROM session_scope WHERE session_id = ?').get(sessionId) ?? null;
33
+ if (!session) {
34
+ // Resolver por cwd no registra selección: sin fila de sesión la autorización es la del proyecto.
35
+ if (sessionOptional) return projectAuthorization(db, projectId);
36
+ return { ok: false, reason: 'session-missing', scopes: null };
37
+ }
38
+ if (session.state === 'expired') return { ok: false, reason: 'session-expired', scopes: null };
39
+ if (session.state === 'invalidated') {
40
+ return { ok: false, reason: 'session-invalidated', invalidReason: session.invalid_reason, scopes: null };
41
+ }
42
+ if (session.project_id !== projectId) {
43
+ return { ok: false, reason: 'selection-changed', projectId: session.project_id, scopes: null };
44
+ }
45
+ const effective = projectAuthorization(db, projectId);
46
+ if (!effective.ok) return effective;
47
+ return { ...effective, revision: session.revision };
48
+ }
49
+
50
+ /**
51
+ * Autorización que no depende de una selección explícita: proyecto activo + grants abiertos +
52
+ * bibliotecas activas.
53
+ *
54
+ * No exige que la biblioteca tenga una raíz autorizada: ése es un estado de *contenido* (una
55
+ * biblioteca recién concedida y todavía sin raíz), no de autorización. Si aquí se filtrara por raíz,
56
+ * el conjunto releído tendría menos ámbitos que la instantánea con la que se abrió la operación y
57
+ * cualquier llamada legítima fallaría con `grant-revoked` —una revocación que nadie hizo— dejando el
58
+ * proyecto inservible. La falta de raíz ya la trata la propia operación (ámbito sin nada que servir).
59
+ */
60
+ export function projectAuthorization(db, projectId) {
61
+ const project = db.prepare('SELECT id, status FROM projects WHERE id = ?').get(projectId) ?? null;
62
+ if (!project) return { ok: false, reason: 'project-missing', scopes: null };
63
+ if (project.status !== 'active') return { ok: false, reason: 'project-archived', scopes: null };
64
+ const libraries = db.prepare(
65
+ `SELECT l.id FROM grants g
66
+ JOIN libraries l ON l.id = g.library_id
67
+ WHERE g.project_id = ? AND g.revoked_at IS NULL AND l.status = 'active'
68
+ ORDER BY l.name, l.id`,
69
+ ).all(projectId).map((row) => row.id);
70
+ return {
71
+ ok: true,
72
+ reason: 'ok',
73
+ projectId,
74
+ revision: null,
75
+ libraries,
76
+ scopes: [projectId, ...libraries],
77
+ };
78
+ }
79
+
80
+ /** Diferencia de conjuntos de ámbitos: `revoked` son los que ya no están, `added` los nuevos. */
81
+ export function diffScopes(before = [], after = []) {
82
+ const previous = new Set(before);
83
+ const current = new Set(after);
84
+ return {
85
+ revoked: [...previous].filter((id) => !current.has(id)),
86
+ added: [...current].filter((id) => !previous.has(id)),
87
+ unchanged: [...current].filter((id) => previous.has(id)),
88
+ };
89
+ }
90
+
91
+ /** Error de revocación con motivo explícito y sin datos sensibles. */
92
+ export function revocationError({ revoked = [], reason = 'revoked-during-operation', tool = null, sessionId = null } = {}) {
93
+ return new RagError('grant-revoked', 'la autorización del ámbito se revocó durante la operación', {
94
+ details: {
95
+ reason,
96
+ tool,
97
+ sessionId,
98
+ scopes: revoked,
99
+ guarantee: 'la operación no devuelve resultados de ámbitos revocados',
100
+ },
101
+ });
102
+ }
103
+
104
+ /**
105
+ * Traduce un estado de autorización perdido a su error del contrato.
106
+ */
107
+ export function authorizationLostError(authorization) {
108
+ if (authorization.reason === 'session-expired') {
109
+ return new RagError('session-expired', 'la sesión expiró durante la operación', { details: { reason: 'session-expired' } });
110
+ }
111
+ if (authorization.reason === 'session-invalidated') {
112
+ return new RagError('scope-forbidden', 'la sesión se invalidó durante la operación', {
113
+ details: { reason: authorization.invalidReason ?? 'admin' },
114
+ });
115
+ }
116
+ if (authorization.reason === 'project-archived') {
117
+ return new RagError('scope-forbidden', 'el proyecto se archivó durante la operación', {
118
+ details: { reason: 'project-archived' },
119
+ });
120
+ }
121
+ return new RagError('scope-forbidden', 'la autorización de la operación dejó de ser válida', {
122
+ details: { reason: authorization.reason },
123
+ });
124
+ }