@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,402 @@
1
+ /**
2
+ * Descubrimiento de proyectos (auto-discovery 01).
3
+ *
4
+ * Reglas de diseño, en corto:
5
+ * - Sólo se escanea dentro de un *workspace confiable*; fuera de él no hay descubrimiento.
6
+ * - Descubrir no es registrar, ni autorizar, ni indexar: este módulo nunca abre almacenes de
7
+ * ámbito y sólo lee `package.json` (≤256 KiB) para clasificar; del resto de indicadores
8
+ * comprueba la existencia.
9
+ * - El registro es idempotente por `pathKey`: un proyecto ya registrado conserva su `id`, su
10
+ * almacén y sus fuentes; sólo se actualizan los metadatos de descubrimiento.
11
+ * - No se atraviesan enlaces/junctions: un enlace dentro del workspace no puede ampliar el
12
+ * ámbito a una ruta externa.
13
+ */
14
+
15
+ import { lstatSync, readdirSync, readFileSync, statSync } from 'node:fs';
16
+ import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
17
+ import { RagError } from './errors.mjs';
18
+ import { addRoot, appendRegistryAudit, createProject, getMeta, getProject, listRoots, setMeta } from './registry.mjs';
19
+ import { assertRootStructure, inspectRoot, normalizeKey } from './roots-structure.mjs';
20
+
21
+ export const DISCOVERY_MAX_DEPTH = 4;
22
+ export const DISCOVERY_MAX_PROJECTS = 200;
23
+ const PACKAGE_LIMIT_BYTES = 256 * 1024;
24
+
25
+ /** Directorios que nunca se recorren, ni se consideran proyectos, ni se indexan. */
26
+ export const IGNORED_DIRECTORIES = Object.freeze([
27
+ '.git', '.hg', '.svn', 'node_modules', 'vendor', 'dist', 'build', 'out', 'target', 'bin', 'obj',
28
+ '.next', '.nuxt', '.output', '.svelte-kit', '__pycache__', '.venv', 'venv', 'env', '.env',
29
+ 'cache', '.cache', '.turbo', '.parcel-cache', 'coverage', '.nyc_output', 'tmp', 'temp', '.tmp',
30
+ '.idea', '.vscode', 'secrets', '.secrets', '.ssh', '.gnupg', 'test-results', 'playwright-report',
31
+ '.pytest_cache', '.mypy_cache', '.gradle', '.terraform', '_audit', 'archivo', 'archive',
32
+ ]);
33
+
34
+ /** Ficheros que nunca se leen ni se indexan, aunque aparezcan en un proyecto. */
35
+ export const SECRET_FILES = Object.freeze([
36
+ '.env', '.env.local', '.env.production', 'id_rsa', 'id_dsa', 'id_ed25519', '.npmrc', '.pypirc',
37
+ '.netrc', 'credentials.json', 'service-account.json', '.htpasswd',
38
+ ]);
39
+
40
+ const IGNORED = new Set(IGNORED_DIRECTORIES.map((name) => name.toLowerCase()));
41
+
42
+ /**
43
+ * Indicadores ordenados de más específico a más genérico. Se comprueba su existencia; sólo
44
+ * `package.json` se lee (para tipo y nombre) y sólo si es pequeño.
45
+ */
46
+ const INDICATORS = Object.freeze([
47
+ { file: 'artisan', type: 'laravel', strong: true },
48
+ { glob: 'nuxt.config.ts', type: 'nuxt', strong: true },
49
+ { glob: 'nuxt.config.js', type: 'nuxt', strong: true },
50
+ { glob: 'vue.config.js', type: 'vue', strong: true },
51
+ { glob: 'angular.json', type: 'angular', strong: true },
52
+ { glob: 'vite.config.ts', type: 'vite', strong: false },
53
+ { glob: 'vite.config.js', type: 'vite', strong: false },
54
+ { file: 'composer.json', type: 'php', strong: true },
55
+ { file: 'package.json', type: 'node', strong: true },
56
+ { glob: '*.sln', type: 'dotnet', strong: true },
57
+ { glob: '*.csproj', type: 'dotnet', strong: true },
58
+ { file: 'pyproject.toml', type: 'python', strong: true },
59
+ { file: 'requirements.txt', type: 'python', strong: true },
60
+ { file: 'setup.py', type: 'python', strong: false },
61
+ { file: 'go.mod', type: 'go', strong: true },
62
+ { file: 'Cargo.toml', type: 'rust', strong: true },
63
+ { file: 'pom.xml', type: 'java', strong: true },
64
+ { file: 'build.gradle', type: 'java', strong: false },
65
+ { file: 'Gemfile', type: 'ruby', strong: true },
66
+ { file: '.git', type: 'git', strong: false },
67
+ { file: 'index.html', type: 'web', strong: false },
68
+ ]);
69
+
70
+ function isSecretFile(name) {
71
+ const lower = name.toLowerCase();
72
+ if (SECRET_FILES.includes(lower)) return true;
73
+ return lower.startsWith('.env.') || lower.endsWith('.pem') || lower.endsWith('.key');
74
+ }
75
+
76
+ function safeEntries(dir) {
77
+ try {
78
+ return readdirSync(dir, { withFileTypes: true });
79
+ } catch {
80
+ return [];
81
+ }
82
+ }
83
+
84
+ function packageInfo(dir) {
85
+ try {
86
+ const file = join(dir, 'package.json');
87
+ const stat = statSync(file);
88
+ if (!stat.isFile() || stat.size > PACKAGE_LIMIT_BYTES) return null;
89
+ const parsed = JSON.parse(readFileSync(file, 'utf8'));
90
+ return parsed && typeof parsed === 'object' ? parsed : null;
91
+ } catch {
92
+ return null;
93
+ }
94
+ }
95
+
96
+ function classifyPackage(pkg, fallbackType) {
97
+ if (!pkg) return fallbackType;
98
+ const all = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}), ...(pkg.peerDependencies ?? {}) };
99
+ const has = (name) => Object.prototype.hasOwnProperty.call(all, name);
100
+ if (has('nuxt') || has('nuxt3')) return 'nuxt';
101
+ if (has('next')) return 'next';
102
+ if (has('vue')) return 'vue';
103
+ if (has('react')) return 'react';
104
+ if (has('@angular/core')) return 'angular';
105
+ if (has('svelte')) return 'svelte';
106
+ return 'node';
107
+ }
108
+
109
+ function detectMarkers(dir) {
110
+ const entries = safeEntries(dir);
111
+ const names = new Set(entries.map((entry) => entry.name));
112
+ const lowerNames = new Map(entries.map((entry) => [entry.name.toLowerCase(), entry.name]));
113
+ const indicators = [];
114
+ let type = null;
115
+ for (const indicator of INDICATORS) {
116
+ if (indicator.file) {
117
+ if (!names.has(indicator.file)) continue;
118
+ indicators.push(indicator.file);
119
+ if (!type) type = indicator.type;
120
+ if (indicator.type === 'node') {
121
+ type = classifyPackage(packageInfo(dir), 'node');
122
+ }
123
+ continue;
124
+ }
125
+ const suffix = indicator.glob.slice(1).toLowerCase();
126
+ const match = entries.find((entry) => entry.name.toLowerCase().endsWith(suffix));
127
+ if (!match) continue;
128
+ indicators.push(lowerNames.get(match.name.toLowerCase()) ?? match.name);
129
+ if (!type) type = indicator.type;
130
+ }
131
+ if (!type) return null;
132
+ // El nombre visible es el del directorio: el nombre del manifiesto puede ser un scope npm
133
+ // (`@local/x`) y confunde al identificar el proyecto en el panel.
134
+ const name = basename(dir);
135
+ const pkg = (type === 'node' || ['vue', 'nuxt', 'react', 'next', 'angular', 'svelte', 'vite'].includes(type))
136
+ ? packageInfo(dir)
137
+ : null;
138
+ const manifestName = pkg && typeof pkg.name === 'string' && pkg.name.trim() !== '' ? pkg.name.trim() : null;
139
+ return { name, manifestName, type, indicators: [...new Set(indicators)] };
140
+ }
141
+
142
+ /** Identidad estable de proyecto derivada de la ruta canónica (no aleatoria: idempotente). */
143
+ export function projectIdFor(pathKey) {
144
+ // 26 caracteres del alfabeto del registro, derivados del hash de la clave canónica. La misma
145
+ // ruta produce siempre el mismo id; una ruta distinta, uno distinto.
146
+ const alphabet = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
147
+ let hash = 0xcbf29ce484222325n;
148
+ const mask = 0xffffffffffffffffn;
149
+ for (const char of pathKey) {
150
+ hash ^= BigInt(char.codePointAt(0));
151
+ hash = (hash * 0x100000001b3n) & mask;
152
+ }
153
+ let out = '';
154
+ let value = hash;
155
+ for (let index = 0; index < 26; index += 1) {
156
+ out += alphabet[Number(value % 32n)];
157
+ value /= 32n;
158
+ if (value === 0n) value = hash ^ BigInt(index + 1);
159
+ }
160
+ return `prj_${out}`;
161
+ }
162
+
163
+ export function projectMetaKey(projectId) {
164
+ return `project_discovery:${projectId}`;
165
+ }
166
+
167
+ export function readProjectMeta(db, projectId) {
168
+ const raw = getMeta(db, projectMetaKey(projectId));
169
+ if (!raw) return null;
170
+ try {
171
+ return JSON.parse(raw);
172
+ } catch {
173
+ return null;
174
+ }
175
+ }
176
+
177
+ function writeProjectMeta(db, projectId, meta) {
178
+ setMeta(db, projectMetaKey(projectId), JSON.stringify(meta));
179
+ }
180
+
181
+ function projectByRootKey(db, pathKey) {
182
+ const row = db.prepare(`SELECT scope_id, path, path_key FROM roots
183
+ WHERE scope_kind='prj' AND path_key = ? LIMIT 1`).get(pathKey);
184
+ if (!row) return null;
185
+ return getProject(db, row.scope_id);
186
+ }
187
+
188
+ function insideAnyRoot(db, pathKey) {
189
+ return listRoots(db).some((root) => root.path_key === pathKey || pathKey.startsWith(`${root.path_key}/`));
190
+ }
191
+
192
+ function auditDiscovery(db, { at, action, target, outcome = 'ok', detail }) {
193
+ try {
194
+ appendRegistryAudit(db, {
195
+ at,
196
+ actor: 'host',
197
+ sessionId: null,
198
+ action,
199
+ target,
200
+ outcome,
201
+ detail: JSON.stringify(detail ?? {}),
202
+ });
203
+ } catch {
204
+ // la auditoría no invalida un descubrimiento ya decidido
205
+ }
206
+ }
207
+
208
+ /**
209
+ * Registra un proyecto descubierto. Idempotente por raíz: si la ruta ya está registrada, no se
210
+ * crea nada y sólo se actualizan los metadatos de descubrimiento.
211
+ *
212
+ * `authorization`:
213
+ * - `'read'` → la raíz queda `authorized` (requiere `trust.readAuthorization`).
214
+ * - `'discovered'`→ el proyecto se registra sin raíz: visible, no resoluble ni indexable.
215
+ */
216
+ export function registerDiscoveredProject(db, {
217
+ path, name, type, indicators = [], source = 'scan', authorization = 'read', now = Date.now(),
218
+ } = {}) {
219
+ if (authorization !== 'read' && authorization !== 'discovered') {
220
+ throw new RagError('invalid-argument', 'authorization debe ser read o discovered');
221
+ }
222
+ const info = assertRootStructure(inspectRoot(path));
223
+ const existingProject = projectByRootKey(db, info.key);
224
+ if (existingProject) {
225
+ const previous = readProjectMeta(db, existingProject.id) ?? {};
226
+ const meta = {
227
+ ...previous,
228
+ path: info.canonical,
229
+ pathKey: info.key,
230
+ type: previous.type ?? type ?? 'unknown',
231
+ indicators: [...new Set([...(previous.indicators ?? []), ...indicators])],
232
+ firstDiscoveredAt: previous.firstDiscoveredAt ?? now,
233
+ lastSeenAt: now,
234
+ source,
235
+ };
236
+ writeProjectMeta(db, existingProject.id, meta);
237
+ return { created: false, projectId: existingProject.id, name: existingProject.name, path: info.canonical };
238
+ }
239
+
240
+ if (authorization === 'discovered') {
241
+ const project = createProject(db, { name: name || basename(info.canonical), now });
242
+ writeProjectMeta(db, project.id, {
243
+ path: info.canonical, pathKey: info.key, type: type ?? 'unknown', indicators,
244
+ firstDiscoveredAt: now, lastSeenAt: now, source, registeredRoot: false,
245
+ });
246
+ auditDiscovery(db, {
247
+ at: now, action: 'project.discover', target: project.id,
248
+ detail: { path: info.canonical, type: type ?? 'unknown', registeredRoot: false },
249
+ });
250
+ return { created: true, projectId: project.id, name: project.name, path: info.canonical, registeredRoot: false };
251
+ }
252
+
253
+ const project = createProject(db, { name: name || basename(info.canonical), now });
254
+ try {
255
+ addRoot(db, {
256
+ scopeKind: 'prj', scopeId: project.id, path: info.canonical, addedBy: 'host', now, allowNested: true,
257
+ });
258
+ } catch (error) {
259
+ // La identidad ya creada sin raíz no se descarta: se documenta como descubierta, no legible.
260
+ writeProjectMeta(db, project.id, {
261
+ path: info.canonical, pathKey: info.key, type: type ?? 'unknown', indicators,
262
+ firstDiscoveredAt: now, lastSeenAt: now, source, registeredRoot: false,
263
+ registrationError: error?.code ?? 'root-registration-failed',
264
+ });
265
+ auditDiscovery(db, {
266
+ at: now, action: 'project.discover', target: project.id, outcome: 'failed',
267
+ detail: { path: info.canonical, code: error?.code ?? 'root-registration-failed' },
268
+ });
269
+ return {
270
+ created: true, projectId: project.id, name: project.name, path: info.canonical,
271
+ registeredRoot: false, error: error?.code ?? 'root-registration-failed',
272
+ };
273
+ }
274
+ writeProjectMeta(db, project.id, {
275
+ path: info.canonical, pathKey: info.key, type: type ?? 'unknown', indicators,
276
+ firstDiscoveredAt: now, lastSeenAt: now, source, registeredRoot: true,
277
+ });
278
+ auditDiscovery(db, {
279
+ at: now, action: 'project.discover', target: project.id,
280
+ detail: { path: info.canonical, type: type ?? 'unknown', registeredRoot: true },
281
+ });
282
+ return { created: true, projectId: project.id, name: project.name, path: info.canonical, registeredRoot: true };
283
+ }
284
+
285
+ /**
286
+ * Escanea un workspace confiable y devuelve lo detectado, sin escribir. El llamador decide si
287
+ * registra (`registerDiscoveredProject`).
288
+ */
289
+ export function scanWorkspace(path, { maxDepth = DISCOVERY_MAX_DEPTH, maxProjects = DISCOVERY_MAX_PROJECTS } = {}) {
290
+ const info = assertRootStructure(inspectRoot(path));
291
+ const rootKey = info.key;
292
+ const found = [];
293
+ const skipped = [];
294
+ const queue = [{ dir: info.canonical, depth: 0 }];
295
+ let visited = 0;
296
+ while (queue.length > 0 && found.length < maxProjects && visited < maxProjects * 40) {
297
+ const { dir, depth } = queue.shift();
298
+ visited += 1;
299
+ const project = detectMarkers(dir);
300
+ if (project) {
301
+ const candidate = inspectRoot(dir);
302
+ if (candidate.key !== rootKey && !candidate.key.startsWith(`${rootKey}/`)) {
303
+ skipped.push({ path: dir, reason: 'outside-trusted-root' });
304
+ } else {
305
+ found.push({
306
+ path: candidate.canonical,
307
+ pathKey: candidate.key,
308
+ name: project.name,
309
+ manifestName: project.manifestName ?? null,
310
+ type: project.type,
311
+ indicators: project.indicators,
312
+ depth,
313
+ });
314
+ }
315
+ }
316
+ if (depth >= maxDepth) continue;
317
+ for (const entry of safeEntries(dir)) {
318
+ if (entry.isSymbolicLink()) {
319
+ skipped.push({ path: join(dir, entry.name), reason: 'symlink' });
320
+ continue;
321
+ }
322
+ if (!entry.isDirectory()) continue;
323
+ if (IGNORED.has(entry.name.toLowerCase())) continue;
324
+ queue.push({ dir: join(dir, entry.name), depth: depth + 1 });
325
+ }
326
+ }
327
+ return { root: info.canonical, rootKey, projects: found, skipped, truncated: found.length >= maxProjects, visited };
328
+ }
329
+
330
+ /**
331
+ * Encuentra el proyecto que contiene un directorio subiendo desde él hasta el workspace
332
+ * confiable. Devuelve el límite **más específico** (el primero con indicadores), nunca el
333
+ * workspace por defecto si el directorio no pertenece a ningún proyecto identificable.
334
+ */
335
+ export function findProjectBoundary(startPath, { withinPath } = {}) {
336
+ if (typeof startPath !== 'string' || !isAbsolute(startPath)) return null;
337
+ let current = resolve(startPath);
338
+ const limitKey = withinPath ? normalizeKey(assertRootStructure(inspectRoot(withinPath)).canonical) : null;
339
+ // Un cwd puede no existir todavía (p. ej. el host informa de un directorio aún no creado):
340
+ // se sube al ancestro existente más cercano sin salir del workspace confiable.
341
+ for (let steps = 0; steps < 64; steps += 1) {
342
+ try {
343
+ lstatSync(current);
344
+ break;
345
+ } catch {
346
+ const parent = dirname(current);
347
+ if (parent === current) return null;
348
+ current = parent;
349
+ }
350
+ }
351
+ for (let steps = 0; steps < 64; steps += 1) {
352
+ let stat;
353
+ try {
354
+ stat = lstatSync(current);
355
+ } catch {
356
+ return null;
357
+ }
358
+ if (stat.isSymbolicLink()) return null;
359
+ if (!stat.isDirectory()) {
360
+ current = dirname(current);
361
+ continue;
362
+ }
363
+ const key = normalizeKey(current);
364
+ if (limitKey && key !== limitKey && !key.startsWith(`${limitKey}/`)) return null;
365
+ const project = detectMarkers(current);
366
+ if (project) {
367
+ const info = assertRootStructure(inspectRoot(current));
368
+ return { path: info.canonical, pathKey: info.key, name: project.name, type: project.type, indicators: project.indicators };
369
+ }
370
+ if (limitKey && key === limitKey) return null;
371
+ const parent = dirname(current);
372
+ if (parent === current) return null;
373
+ current = parent;
374
+ }
375
+ return null;
376
+ }
377
+
378
+ export function describeProject(db, projectId) {
379
+ const project = getProject(db, projectId);
380
+ if (!project) return null;
381
+ const meta = readProjectMeta(db, projectId) ?? {};
382
+ const roots = db.prepare(`SELECT path, state FROM roots WHERE scope_kind='prj' AND scope_id=? ORDER BY path`).all(projectId);
383
+ return {
384
+ id: project.id,
385
+ name: project.name,
386
+ status: project.status,
387
+ type: meta.type ?? 'unknown',
388
+ indicators: meta.indicators ?? [],
389
+ discoveredAt: meta.firstDiscoveredAt ?? null,
390
+ lastSeenAt: meta.lastSeenAt ?? null,
391
+ registeredRoot: meta.registeredRoot !== false,
392
+ roots: roots.map((row) => ({ path: row.path, state: row.state })),
393
+ };
394
+ }
395
+
396
+ export function isIgnoredDirectory(name) {
397
+ return IGNORED.has(String(name).toLowerCase());
398
+ }
399
+
400
+ export function isSecretFileName(name) {
401
+ return isSecretFile(String(name));
402
+ }
package/lib/doctor.mjs ADDED
@@ -0,0 +1,82 @@
1
+ /**
2
+ * Diagnóstico del almacén y del runtime (AC13). No escribe nada: sólo mide y explica.
3
+ */
4
+
5
+ import { constants, accessSync, existsSync, statSync } from 'node:fs';
6
+ import { dirname } from 'node:path';
7
+
8
+ import { auditState } from './audit-export.mjs';
9
+ import { closeDatabase, ftsIntegrityCheck, openDatabase } from './db.mjs';
10
+ import { embedText } from './embed.mjs';
11
+ import { ragRoot } from './paths.mjs';
12
+ import { resolveConfig, resolveProfileKey } from './config-resolve.mjs';
13
+
14
+ function check(name, run) {
15
+ try {
16
+ const detail = run();
17
+ return { name, status: detail?.status ?? 'ok', detail: detail?.detail ?? String(detail ?? '') };
18
+ } catch (error) {
19
+ return { name, status: 'fail', detail: error?.code ?? error?.message ?? String(error) };
20
+ }
21
+ }
22
+
23
+ /**
24
+ * @param {{root?:string, env?:object}} [options]
25
+ * @returns {{ok:boolean, root:string, checks:Array<{name:string,status:'ok'|'warn'|'fail',detail:string}>}}
26
+ */
27
+ export function runDoctor({ root = ragRoot(process.env), env = process.env } = {}) {
28
+ const checks = [];
29
+
30
+ checks.push(check('runtime', () => {
31
+ const [major, minor] = process.versions.node.split('.').map(Number);
32
+ const ok = major > 22 || (major === 22 && minor >= 5);
33
+ return { status: ok ? 'ok' : 'fail', detail: `node ${process.versions.node}${ok ? '' : ' (necesita >=22.5 para node:sqlite)'}` };
34
+ }));
35
+
36
+ checks.push(check('raíz', () => {
37
+ if (!root || typeof root !== 'string') return { status: 'fail', detail: 'sin raíz de almacén' };
38
+ if (existsSync(root)) {
39
+ if (!statSync(root).isDirectory()) return { status: 'fail', detail: `${root} no es un directorio` };
40
+ accessSync(root, constants.W_OK);
41
+ return { status: 'ok', detail: root };
42
+ }
43
+ accessSync(dirname(root), constants.W_OK);
44
+ return { status: 'warn', detail: `${root} aún no existe (se creará en la primera ingesta)` };
45
+ }));
46
+
47
+ let config;
48
+ checks.push(check('configuración', () => {
49
+ config = resolveConfig({ dataRoot: root, profileKey: resolveProfileKey(env) }).config;
50
+ return { status: 'ok', detail: `embedder ${config.embedding.provider} (${config.embedding.dim} dim)` };
51
+ }));
52
+
53
+ checks.push(check('embedder', () => {
54
+ const active = config ?? resolveConfig({ dataRoot: root, profileKey: resolveProfileKey(env) }).config;
55
+ const vector = embedText('prueba determinista', { provider: active.embedding.provider, dim: active.embedding.dim });
56
+ const again = embedText('prueba determinista', { provider: active.embedding.provider, dim: active.embedding.dim });
57
+ const same = vector.length === again.length && vector.every((value, index) => value === again[index]);
58
+ return { status: same ? 'ok' : 'fail', detail: `${vector.length} dimensiones, ${same ? 'determinista' : 'inestable'}` };
59
+ }));
60
+
61
+ checks.push(check('almacén', () => {
62
+ if (!existsSync(root)) return { status: 'warn', detail: 'no inicializado' };
63
+ const opened = openDatabase({ root, create: false });
64
+ try {
65
+ const tables = opened.db.prepare("SELECT COUNT(*) AS n FROM sqlite_master WHERE type = 'table'").get().n;
66
+ ftsIntegrityCheck(opened.db);
67
+ if (!existsSync(opened.paths.audit)) {
68
+ const chain = auditState(opened.db, { path: opened.paths.audit });
69
+ if (!chain.ok && chain.where === 'database') return { status: 'fail', detail: `auditoría: ${chain.reason}` };
70
+ return { status: 'warn', detail: `esquema v${opened.db.prepare('PRAGMA user_version').get().user_version}, FTS íntegra, sin exportación JSONL (derivable)` };
71
+ }
72
+ const audit = auditState(opened.db, { path: opened.paths.audit });
73
+ if (!audit.ok) return { status: 'fail', detail: `auditoría: ${audit.where}/${audit.reason}` };
74
+ return { status: 'ok', detail: `esquema v${opened.db.prepare('PRAGMA user_version').get().user_version}, ${tables} tablas, FTS íntegra, ${audit.entries} entradas de auditoría` };
75
+ } finally {
76
+ closeDatabase(opened.db);
77
+ }
78
+ }));
79
+
80
+ const ok = checks.every((item) => item.status !== 'fail');
81
+ return { ok, root, checks };
82
+ }
package/lib/embed.mjs ADDED
@@ -0,0 +1,96 @@
1
+ /**
2
+ * Embeddings locales deterministas (`local-hash-v1`).
3
+ *
4
+ * Esto es **hashing léxico con signo**, no un modelo neuronal. Sirve para recuperación por similitud
5
+ * aproximada de vocabulario y para que el sistema funcione sin red ni credenciales; no captura
6
+ * sinonimia ni paráfrasis. La documentación y los benchmarks deben decirlo así (P1.6 del plan v2).
7
+ *
8
+ * Garantías: mismo texto → mismo vector, en cualquier máquina y ejecución; vector L2-normalizado;
9
+ * dimensión fija y declarada en `meta.embedding_model` / `vectors.model`.
10
+ */
11
+
12
+ import { createHash } from 'node:crypto';
13
+
14
+ import { RagError } from './errors.mjs';
15
+
16
+ export const LOCAL_PROVIDER = 'local-hash-v1';
17
+ export const DEFAULT_DIM = 256;
18
+ export const SUPPORTED_PROVIDERS = Object.freeze([LOCAL_PROVIDER]);
19
+
20
+ /** Tokens Unicode (letras/números) en minúsculas. Sin stemming: el corpus se indexa tal cual. */
21
+ export function tokenize(text) {
22
+ return String(text).normalize('NFC').toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
23
+ }
24
+
25
+ function hashPair(value) {
26
+ const digest = createHash('sha256').update(value, 'utf8').digest();
27
+ return { bucket: digest.readUInt32LE(0), sign: (digest[4] & 1) === 0 ? 1 : -1 };
28
+ }
29
+
30
+ /**
31
+ * Vector de un texto.
32
+ * @param {string} text
33
+ * @param {{dim?:number, provider?:string}} options
34
+ * @returns {Float32Array}
35
+ */
36
+ export function embedText(text, options = {}) {
37
+ const provider = options.provider ?? LOCAL_PROVIDER;
38
+ const dim = options.dim ?? DEFAULT_DIM;
39
+ if (!SUPPORTED_PROVIDERS.includes(provider)) {
40
+ throw new RagError('invalid-config', `proveedor de embeddings no soportado: ${provider}`);
41
+ }
42
+ if (!Number.isInteger(dim) || dim < 32 || dim > 4_096) {
43
+ throw new RagError('invalid-config', `dimensión de embedding inválida: ${dim}`);
44
+ }
45
+ if (typeof text !== 'string' || text.trim() === '') {
46
+ throw new RagError('invalid-argument', 'no se puede embeber un texto vacío');
47
+ }
48
+
49
+ const tokens = tokenize(text);
50
+ if (tokens.length === 0) throw new RagError('invalid-argument', 'el texto no contiene tokens');
51
+
52
+ const vector = new Float32Array(dim);
53
+ const counts = new Map();
54
+ for (const token of tokens) counts.set(token, (counts.get(token) ?? 0) + 1);
55
+ for (const [token, count] of counts) {
56
+ const { bucket, sign } = hashPair(token);
57
+ vector[bucket % dim] += sign * (1 + Math.log1p(count));
58
+ }
59
+ // Bigramas con medio peso: dan algo de orden sin convertirlo en un modelo de frases.
60
+ for (let i = 0; i + 1 < tokens.length; i += 1) {
61
+ const { bucket, sign } = hashPair(`${tokens[i]} ${tokens[i + 1]}`);
62
+ vector[bucket % dim] += sign * 0.5;
63
+ }
64
+
65
+ let norm = 0;
66
+ for (const value of vector) norm += value * value;
67
+ norm = Math.sqrt(norm);
68
+ if (norm > 0) for (let i = 0; i < dim; i += 1) vector[i] /= norm;
69
+ return vector;
70
+ }
71
+
72
+ /** Producto escalar de dos vectores normalizados = similitud coseno. */
73
+ export function cosine(a, b) {
74
+ if (a.length !== b.length) throw new RagError('internal', 'vectores de dimensión distinta');
75
+ let sum = 0;
76
+ for (let i = 0; i < a.length; i += 1) sum += a[i] * b[i];
77
+ return sum;
78
+ }
79
+
80
+ /** `Float32Array` → BLOB (copia little-endian del buffer). */
81
+ export function vectorToBlob(vector) {
82
+ if (!(vector instanceof Float32Array)) throw new RagError('internal', 'vectorToBlob espera Float32Array');
83
+ return new Uint8Array(vector.buffer.slice(vector.byteOffset, vector.byteOffset + vector.byteLength));
84
+ }
85
+
86
+ /** BLOB → `Float32Array`; un tamaño que no sea múltiplo de 4 es corrupción. */
87
+ export function blobToVector(blob, { dim } = {}) {
88
+ if (!(blob instanceof Uint8Array)) throw new RagError('store-corrupt', 'vector almacenado con tipo inválido');
89
+ if (blob.byteLength % 4 !== 0) throw new RagError('store-corrupt', 'vector almacenado con longitud inválida');
90
+ const copy = blob.buffer.slice(blob.byteOffset, blob.byteOffset + blob.byteLength);
91
+ const vector = new Float32Array(copy);
92
+ if (dim !== undefined && vector.length !== dim) {
93
+ throw new RagError('store-corrupt', `vector de dimensión ${vector.length}, se esperaba ${dim}`);
94
+ }
95
+ return vector;
96
+ }
@@ -0,0 +1,103 @@
1
+ /**
2
+ * Abstracción de proveedores de embeddings (M1).
3
+ *
4
+ * Dos implementaciones reales:
5
+ * - `local-hash-v1`: hashing léxico determinista, sin red. Es el valor por defecto y **no** se presenta
6
+ * como semántico.
7
+ * - `remote`: cualquier endpoint compatible con `POST {input:[...], model}` que devuelva
8
+ * `{data:[{embedding:[...]}]}` (forma OpenAI). Sólo se usa si la configuración lo declara y la capa que
9
+ * llama obtiene aprobación de egreso; este módulo no aprueba nada por sí mismo.
10
+ *
11
+ * El contrato es asíncrono desde el principio aunque el proveedor local resuelva en microtarea: así el
12
+ * motor no queda atado a que todos los proveedores sean síncronos.
13
+ */
14
+
15
+ import { RagError } from './errors.mjs';
16
+ import { embedText, LOCAL_PROVIDER } from './embed.mjs';
17
+
18
+ function localEmbedder({ dim }) {
19
+ return {
20
+ id: LOCAL_PROVIDER,
21
+ model: LOCAL_PROVIDER,
22
+ dim,
23
+ kind: 'lexical',
24
+ async embed(texts) {
25
+ return texts.map((text) => embedText(text, { provider: LOCAL_PROVIDER, dim }));
26
+ },
27
+ };
28
+ }
29
+
30
+ function remoteEmbedder({ dim, remote }, { fetchImpl, credential }) {
31
+ const model = `remote:${remote.model}`;
32
+ return {
33
+ id: 'remote',
34
+ model,
35
+ dim,
36
+ kind: 'semantic',
37
+ async embed(texts) {
38
+ const vectors = [];
39
+ for (let offset = 0; offset < texts.length; offset += remote.batchSize) {
40
+ const batch = texts.slice(offset, offset + remote.batchSize);
41
+ const controller = new AbortController();
42
+ const timer = setTimeout(() => controller.abort(), remote.timeoutMs);
43
+ let response;
44
+ try {
45
+ response = await fetchImpl(remote.endpoint, {
46
+ method: 'POST',
47
+ headers: {
48
+ 'content-type': 'application/json',
49
+ ...(credential ? { authorization: `Bearer ${credential}` } : {}),
50
+ },
51
+ body: JSON.stringify({ model: remote.model, input: batch }),
52
+ signal: controller.signal,
53
+ });
54
+ } catch (cause) {
55
+ throw new RagError('embedding-failed', 'no se pudo contactar con el proveedor de embeddings', { cause });
56
+ } finally {
57
+ clearTimeout(timer);
58
+ }
59
+ if (!response.ok) {
60
+ throw new RagError('embedding-failed', `el proveedor respondió ${response.status}`, {
61
+ details: { status: response.status },
62
+ });
63
+ }
64
+ let payload;
65
+ try {
66
+ payload = await response.json();
67
+ } catch (cause) {
68
+ throw new RagError('embedding-failed', 'el proveedor no devolvió JSON válido', { cause });
69
+ }
70
+ const data = Array.isArray(payload?.data) ? payload.data : null;
71
+ if (!data || data.length !== batch.length) {
72
+ throw new RagError('embedding-failed', 'el proveedor devolvió un número de vectores inesperado', {
73
+ details: { expected: batch.length, received: data?.length ?? null },
74
+ });
75
+ }
76
+ for (const item of data) {
77
+ const embedding = item?.embedding;
78
+ if (!Array.isArray(embedding) || embedding.length !== dim) {
79
+ throw new RagError('embedding-failed', 'vector con dimensión incorrecta', {
80
+ details: { expected: dim, received: Array.isArray(embedding) ? embedding.length : null },
81
+ });
82
+ }
83
+ vectors.push(Float32Array.from(embedding, Number));
84
+ }
85
+ }
86
+ return vectors;
87
+ },
88
+ };
89
+ }
90
+
91
+ /**
92
+ * Construye el proveedor declarado por la configuración. `fetchImpl` y `credential` se inyectan desde el
93
+ * llamador: los tests no salen a la red y el egress sólo ocurre con autorización explícita.
94
+ */
95
+ export function createEmbedder(config, { fetchImpl = globalThis.fetch, credential = null } = {}) {
96
+ const embedding = config.embedding;
97
+ if (embedding.provider === LOCAL_PROVIDER) return localEmbedder({ dim: embedding.dim });
98
+ if (embedding.provider === 'remote') {
99
+ if (embedding.remote === null) throw new RagError('invalid-config', 'falta embedding.remote');
100
+ return remoteEmbedder({ dim: embedding.dim, remote: embedding.remote }, { fetchImpl, credential });
101
+ }
102
+ throw new RagError('invalid-config', `proveedor de embeddings desconocido: ${embedding.provider}`);
103
+ }