@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
package/lib/search.mjs
ADDED
|
@@ -0,0 +1,345 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Recuperación v0.2 (M1): híbrida configurable con diagnóstico.
|
|
3
|
+
*
|
|
4
|
+
* - Léxica: FTS5/BM25 (siempre disponible, sin red).
|
|
5
|
+
* - Semántica: vectores del proveedor configurado (local determinista o remoto aprobado). El motor no
|
|
6
|
+
* decide si el proveedor es semántico: lo declara el proveedor (`kind`).
|
|
7
|
+
* - Fusión: Reciprocal Rank Fusion **ponderada** (`peso / (k + rango)`), porque BM25 y coseno no son
|
|
8
|
+
* comparables; los pesos permiten priorizar una vía sin calibrar escalas.
|
|
9
|
+
*
|
|
10
|
+
* La consulta vectorial está acotada (`search.maxVectorScan`) y lo declara. `minScore` se aplica sobre la
|
|
11
|
+
* puntuación normalizada 0..1 de la lista fusionada; `maxPerSource` limita cuántos fragmentos aporta una
|
|
12
|
+
* misma fuente. Ambas cosas se documentan como parte del resultado (`diagnostics`).
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
import { RagError } from './errors.mjs';
|
|
16
|
+
import { normalizeTags } from './tags.mjs';
|
|
17
|
+
import { blobToVector, cosine } from './embed.mjs';
|
|
18
|
+
import { createEmbedder } from './embedders.mjs';
|
|
19
|
+
import { latencyBucket, recordMetrics } from './metrics.mjs';
|
|
20
|
+
|
|
21
|
+
export const RRF_K = 60;
|
|
22
|
+
export const SNIPPET_CHARS = 240;
|
|
23
|
+
|
|
24
|
+
/** Tokens de consulta; vacío es un error de argumento, no «devuelve todo». */
|
|
25
|
+
export function queryTokens(query) {
|
|
26
|
+
const tokens = String(query ?? '').normalize('NFC').match(/[\p{L}\p{N}]+/gu) ?? [];
|
|
27
|
+
if (tokens.length === 0) throw new RagError('invalid-argument', 'la consulta no contiene términos');
|
|
28
|
+
return tokens;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Expresión MATCH segura: cada token va entrecomillado (sin operadores del usuario) y con prefijo.
|
|
33
|
+
* Primero AND (precisión); el llamador puede pedir OR si AND no devuelve nada.
|
|
34
|
+
*/
|
|
35
|
+
export function buildFtsQuery(query, { operator = 'AND' } = {}) {
|
|
36
|
+
return queryTokens(query).map((token) => `"${token.replace(/"/g, '""')}"*`).join(` ${operator} `);
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
function filterSql({ collection, tags, tagMode }, params, alias = 's') {
|
|
40
|
+
let sql = '';
|
|
41
|
+
if (collection !== undefined && collection !== null) {
|
|
42
|
+
sql += ` AND ${alias}.collection = ?`;
|
|
43
|
+
params.push(collection);
|
|
44
|
+
}
|
|
45
|
+
if (Array.isArray(tags) && tags.length > 0) {
|
|
46
|
+
if (tagMode === 'all') {
|
|
47
|
+
for (const tag of tags) {
|
|
48
|
+
sql += ` AND EXISTS (SELECT 1 FROM source_tags t WHERE t.source_id = ${alias}.id AND t.tag = ?)`;
|
|
49
|
+
params.push(tag);
|
|
50
|
+
}
|
|
51
|
+
} else {
|
|
52
|
+
sql += ` AND EXISTS (SELECT 1 FROM source_tags t WHERE t.source_id = ${alias}.id AND t.tag IN (${tags.map(() => '?').join(',')}))`;
|
|
53
|
+
params.push(...tags);
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
return sql;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** Búsqueda FTS. Devuelve filas con `rank` 1..n y la puntuación bm25 (más negativa = mejor). */
|
|
60
|
+
export function ftsSearch(db, { query, limit, collection, tags, tagMode, operator = 'AND' }) {
|
|
61
|
+
const params = [];
|
|
62
|
+
const match = buildFtsQuery(query, { operator });
|
|
63
|
+
const where = filterSql({ collection, tags, tagMode }, params);
|
|
64
|
+
const sql = `SELECT c.chunk_key, c.source_id, c.ordinal, c.title, c.heading, c.text, c.char_start, c.char_end,
|
|
65
|
+
s.uri, s.collection, s.title AS source_title,
|
|
66
|
+
bm25(chunks_fts) AS bm25,
|
|
67
|
+
snippet(chunks_fts, 0, '[', ']', ' … ', 12) AS snippet
|
|
68
|
+
FROM chunks_fts
|
|
69
|
+
JOIN chunks c ON c.id = chunks_fts.rowid
|
|
70
|
+
JOIN sources s ON s.id = c.source_id
|
|
71
|
+
WHERE chunks_fts MATCH ?${where}
|
|
72
|
+
ORDER BY bm25(chunks_fts) ASC, c.chunk_key ASC
|
|
73
|
+
LIMIT ?`;
|
|
74
|
+
const rows = db.prepare(sql).all(match, ...params, limit);
|
|
75
|
+
return rows.map((row, index) => ({ ...row, rank: index + 1 }));
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** Escaneo de vectores con un vector de consulta ya calculado. */
|
|
79
|
+
export function vectorSearch(db, { queryVector, limit, collection, tags, tagMode, model, dim, config }) {
|
|
80
|
+
const params = [model];
|
|
81
|
+
const where = filterSql({ collection, tags, tagMode }, params);
|
|
82
|
+
const cap = config.search.maxVectorScan;
|
|
83
|
+
const sql = `SELECT v.chunk_key, v.vec, c.source_id, c.ordinal, c.title, c.heading, c.text, c.char_start, c.char_end, s.uri, s.collection, s.title AS source_title
|
|
84
|
+
FROM vectors v
|
|
85
|
+
JOIN chunks c ON c.chunk_key = v.chunk_key
|
|
86
|
+
JOIN sources s ON s.id = c.source_id
|
|
87
|
+
WHERE v.model = ?${where}
|
|
88
|
+
LIMIT ?`;
|
|
89
|
+
const rows = db.prepare(sql).all(...params, cap + 1);
|
|
90
|
+
const truncated = rows.length > cap;
|
|
91
|
+
const scored = [];
|
|
92
|
+
for (const row of rows.slice(0, cap)) {
|
|
93
|
+
const vector = blobToVector(row.vec, { dim });
|
|
94
|
+
scored.push({ ...row, score: cosine(queryVector, vector) });
|
|
95
|
+
}
|
|
96
|
+
scored.sort((a, b) => b.score - a.score || a.chunk_key.localeCompare(b.chunk_key));
|
|
97
|
+
return {
|
|
98
|
+
truncated,
|
|
99
|
+
scanned: Math.min(rows.length, cap),
|
|
100
|
+
rows: scored.slice(0, limit).map((row, index) => ({ ...row, rank: index + 1 })),
|
|
101
|
+
};
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* Fusión RRF ponderada. `weights` sólo escala la contribución de cada lista; no mezcla escalas.
|
|
106
|
+
* @returns {Array<object>} resultados ordenados por puntuación descendente
|
|
107
|
+
*/
|
|
108
|
+
export function fuseRrf(ftsRows, vectorRows, { k = RRF_K, limit, weights = { lexical: 1, semantic: 1 } } = {}) {
|
|
109
|
+
const byKey = new Map();
|
|
110
|
+
const add = (row, source) => {
|
|
111
|
+
const entry = byKey.get(row.chunk_key) ?? {
|
|
112
|
+
chunkKey: row.chunk_key,
|
|
113
|
+
sourceId: row.source_id,
|
|
114
|
+
uri: row.uri,
|
|
115
|
+
collection: row.collection,
|
|
116
|
+
title: row.title,
|
|
117
|
+
sourceTitle: row.source_title,
|
|
118
|
+
heading: row.heading ?? null,
|
|
119
|
+
ordinal: row.ordinal,
|
|
120
|
+
text: row.text,
|
|
121
|
+
charStart: row.char_start,
|
|
122
|
+
charEnd: row.char_end,
|
|
123
|
+
snippet: row.snippet ?? null,
|
|
124
|
+
rrf: 0,
|
|
125
|
+
bm25: null,
|
|
126
|
+
cosine: null,
|
|
127
|
+
rankFts: null,
|
|
128
|
+
rankVector: null,
|
|
129
|
+
via: [],
|
|
130
|
+
};
|
|
131
|
+
const weight = source === 'fts' ? weights.lexical : weights.semantic;
|
|
132
|
+
entry.rrf += weight / (k + row.rank);
|
|
133
|
+
entry.via.push(source);
|
|
134
|
+
if (source === 'fts') { entry.rankFts = row.rank; entry.bm25 = row.bm25; entry.snippet = row.snippet ?? entry.snippet; }
|
|
135
|
+
else { entry.rankVector = row.rank; entry.cosine = row.score; }
|
|
136
|
+
byKey.set(row.chunk_key, entry);
|
|
137
|
+
};
|
|
138
|
+
for (const row of ftsRows) add(row, 'fts');
|
|
139
|
+
for (const row of vectorRows) add(row, 'vector');
|
|
140
|
+
const rows = [...byKey.values()].sort((a, b) => b.rrf - a.rrf || a.chunkKey.localeCompare(b.chunkKey));
|
|
141
|
+
const max = rows[0]?.rrf || Number.EPSILON;
|
|
142
|
+
for (const row of rows) row.score = Math.max(0, Math.min(1, row.rrf / max));
|
|
143
|
+
return { rows: rows.slice(0, limit), all: rows };
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/**
|
|
147
|
+
* Aplica corte por relevancia y límite de fragmentos por fuente. Se hace después de fusionar para que el
|
|
148
|
+
* corte no dependa de qué vía encontró cada fragmento.
|
|
149
|
+
*/
|
|
150
|
+
export function constrainResults(rows, { minScore = 0, maxPerSource = 0 } = {}) {
|
|
151
|
+
const filtered = rows.filter((row) => row.score >= minScore);
|
|
152
|
+
if (maxPerSource <= 0) return filtered;
|
|
153
|
+
const perSource = new Map();
|
|
154
|
+
const kept = [];
|
|
155
|
+
for (const row of filtered) {
|
|
156
|
+
const count = perSource.get(row.sourceId) ?? 0;
|
|
157
|
+
if (count >= maxPerSource) continue;
|
|
158
|
+
perSource.set(row.sourceId, count + 1);
|
|
159
|
+
kept.push(row);
|
|
160
|
+
}
|
|
161
|
+
return kept;
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
/**
|
|
165
|
+
* Selección documental sobre resultados ya ordenados por el ranking actual (RAG-RANKING-04).
|
|
166
|
+
*
|
|
167
|
+
* Primera vuelta: la primera fila de cada `sourceId`, en el orden recibido; esa primera aparición
|
|
168
|
+
* cuenta para `maxPerSource`. Segunda vuelta: rellena las posiciones restantes con los candidatos
|
|
169
|
+
* sobrantes, respetando el tope por fuente. No recalcula puntuaciones, no muta las filas y es
|
|
170
|
+
* determinista e idempotente. `maxPerSource = 0` significa sin tope.
|
|
171
|
+
*/
|
|
172
|
+
export function selectBySource(rows, { limit, maxPerSource = 0 } = {}) {
|
|
173
|
+
const list = Array.isArray(rows) ? rows : [];
|
|
174
|
+
const cap = maxPerSource > 0 ? maxPerSource : Number.POSITIVE_INFINITY;
|
|
175
|
+
const max = Number.isInteger(limit) && limit > 0 ? limit : list.length;
|
|
176
|
+
const counts = new Map();
|
|
177
|
+
const first = [];
|
|
178
|
+
const taken = new Set();
|
|
179
|
+
for (let index = 0; index < list.length && first.length < max; index += 1) {
|
|
180
|
+
const row = list[index];
|
|
181
|
+
const key = row.sourceId ?? row.source_id;
|
|
182
|
+
if (counts.has(key)) continue;
|
|
183
|
+
counts.set(key, 1);
|
|
184
|
+
first.push(row);
|
|
185
|
+
taken.add(index);
|
|
186
|
+
}
|
|
187
|
+
const out = [...first];
|
|
188
|
+
for (let index = 0; index < list.length && out.length < max; index += 1) {
|
|
189
|
+
if (taken.has(index)) continue;
|
|
190
|
+
const row = list[index];
|
|
191
|
+
const key = row.sourceId ?? row.source_id;
|
|
192
|
+
const count = counts.get(key) ?? 0;
|
|
193
|
+
if (count >= cap) continue;
|
|
194
|
+
counts.set(key, count + 1);
|
|
195
|
+
out.push(row);
|
|
196
|
+
}
|
|
197
|
+
return out.slice(0, max);
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
function recordQuery(db, { elapsedMs, count, strategy, mode, now }) {
|
|
201
|
+
try {
|
|
202
|
+
recordMetrics(db, [
|
|
203
|
+
{ metric: 'query.count', value: 1, dim: strategy, at: now },
|
|
204
|
+
{ metric: 'query.ms', value: Math.max(0, elapsedMs), dim: strategy, at: now },
|
|
205
|
+
{ metric: 'query.ms_bucket', value: 1, dim: latencyBucket(elapsedMs), at: now },
|
|
206
|
+
...(count === 0 ? [{ metric: 'query.empty', value: 1, dim: strategy, at: now }] : []),
|
|
207
|
+
]);
|
|
208
|
+
} catch (error) {
|
|
209
|
+
if (error instanceof RagError && error.code === 'store-busy') return;
|
|
210
|
+
// Una métrica nunca puede convertir una consulta correcta en un fallo.
|
|
211
|
+
}
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
/**
|
|
215
|
+
* Búsqueda completa.
|
|
216
|
+
* @returns {{results:Array, vectors:{scanned:number, truncated:boolean}, diagnostics:object, elapsedMs:number, mode:string}}
|
|
217
|
+
*/
|
|
218
|
+
export async function search(db, {
|
|
219
|
+
query,
|
|
220
|
+
limit = undefined,
|
|
221
|
+
collection = undefined,
|
|
222
|
+
tags = undefined,
|
|
223
|
+
tagMode = 'any',
|
|
224
|
+
strategy = undefined,
|
|
225
|
+
diversity = 'fragment',
|
|
226
|
+
config,
|
|
227
|
+
embedder = undefined,
|
|
228
|
+
record = true,
|
|
229
|
+
now = Date.now(),
|
|
230
|
+
} = {}) {
|
|
231
|
+
const started = process.hrtime.bigint();
|
|
232
|
+
const cap = Math.min(limit ?? config.search.limit, config.search.maxLimit);
|
|
233
|
+
if (!Number.isInteger(cap) || cap < 1) throw new RagError('invalid-argument', 'límite de búsqueda inválido');
|
|
234
|
+
const chosen = strategy ?? config.search.strategy;
|
|
235
|
+
if (!['hybrid', 'fts', 'vector'].includes(chosen)) throw new RagError('invalid-argument', `estrategia desconocida: ${chosen}`);
|
|
236
|
+
const normalizedTags = normalizeTags(tags ?? undefined);
|
|
237
|
+
const weights = config.search.weights;
|
|
238
|
+
|
|
239
|
+
const ftsStarted = process.hrtime.bigint();
|
|
240
|
+
let fts = [];
|
|
241
|
+
let mode = 'none';
|
|
242
|
+
if (chosen !== 'vector') {
|
|
243
|
+
fts = ftsSearch(db, { query, limit: cap * 3, collection, tags: normalizedTags, tagMode, operator: 'AND' });
|
|
244
|
+
mode = 'and';
|
|
245
|
+
if (fts.length === 0) {
|
|
246
|
+
fts = ftsSearch(db, { query, limit: cap * 3, collection, tags: normalizedTags, tagMode, operator: 'OR' });
|
|
247
|
+
mode = fts.length === 0 ? 'none' : 'or';
|
|
248
|
+
}
|
|
249
|
+
}
|
|
250
|
+
const ftsMs = Number(process.hrtime.bigint() - ftsStarted) / 1e6;
|
|
251
|
+
|
|
252
|
+
let vectorResult = { rows: [], truncated: false, scanned: 0 };
|
|
253
|
+
let vectorMs = 0;
|
|
254
|
+
if (chosen !== 'fts') {
|
|
255
|
+
const vectorStarted = process.hrtime.bigint();
|
|
256
|
+
const provider = embedder ?? createEmbedder(config);
|
|
257
|
+
const [queryVector] = await provider.embed([String(query)]);
|
|
258
|
+
vectorResult = vectorSearch(db, {
|
|
259
|
+
queryVector,
|
|
260
|
+
limit: cap * 3,
|
|
261
|
+
collection,
|
|
262
|
+
tags: normalizedTags,
|
|
263
|
+
tagMode,
|
|
264
|
+
model: provider.model,
|
|
265
|
+
dim: provider.dim,
|
|
266
|
+
config,
|
|
267
|
+
});
|
|
268
|
+
vectorMs = Number(process.hrtime.bigint() - vectorStarted) / 1e6;
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
let results;
|
|
272
|
+
let fusion = null;
|
|
273
|
+
if (chosen === 'fts') {
|
|
274
|
+
const ftsPool = fts.map((row, index) => ({
|
|
275
|
+
chunkKey: row.chunk_key,
|
|
276
|
+
sourceId: row.source_id,
|
|
277
|
+
uri: row.uri,
|
|
278
|
+
collection: row.collection,
|
|
279
|
+
title: row.title,
|
|
280
|
+
sourceTitle: row.source_title,
|
|
281
|
+
heading: row.heading ?? null,
|
|
282
|
+
ordinal: row.ordinal,
|
|
283
|
+
text: row.text,
|
|
284
|
+
charStart: row.char_start,
|
|
285
|
+
charEnd: row.char_end,
|
|
286
|
+
snippet: row.snippet ?? null,
|
|
287
|
+
rrf: 1 / (RRF_K + index + 1),
|
|
288
|
+
score: 1,
|
|
289
|
+
rankFts: index + 1,
|
|
290
|
+
rankVector: null,
|
|
291
|
+
bm25: row.bm25,
|
|
292
|
+
cosine: null,
|
|
293
|
+
via: ['fts'],
|
|
294
|
+
}));
|
|
295
|
+
results = (diversity === 'source'
|
|
296
|
+
? selectBySource(ftsPool, { limit: cap, maxPerSource: config.search.maxPerSource })
|
|
297
|
+
: ftsPool).slice(0, cap);
|
|
298
|
+
} else {
|
|
299
|
+
fusion = fuseRrf(fts, vectorResult.rows, { k: config.search.rrfK, limit: cap * 3, weights });
|
|
300
|
+
// En `source` el tope por fuente lo aplica la selección documental, que además rellena posiciones.
|
|
301
|
+
const pool = constrainResults(fusion.all, {
|
|
302
|
+
minScore: config.search.minScore,
|
|
303
|
+
maxPerSource: diversity === 'source' ? 0 : config.search.maxPerSource,
|
|
304
|
+
});
|
|
305
|
+
const selected = diversity === 'source'
|
|
306
|
+
? selectBySource(pool, { limit: cap, maxPerSource: config.search.maxPerSource })
|
|
307
|
+
: pool;
|
|
308
|
+
results = selected.slice(0, cap).map((row) => ({ ...row, score: Math.round(row.score * 1000) / 1000 }));
|
|
309
|
+
}
|
|
310
|
+
|
|
311
|
+
const elapsedMs = Number(process.hrtime.bigint() - started) / 1e6;
|
|
312
|
+
if (record) recordQuery(db, { elapsedMs, count: results.length, strategy: chosen, mode, now });
|
|
313
|
+
|
|
314
|
+
return {
|
|
315
|
+
results,
|
|
316
|
+
vectors: { scanned: vectorResult.scanned, truncated: vectorResult.truncated },
|
|
317
|
+
diagnostics: {
|
|
318
|
+
strategy: chosen,
|
|
319
|
+
lexical: { hits: fts.length, ms: Math.round(ftsMs * 100) / 100, mode },
|
|
320
|
+
semantic: { hits: vectorResult.scanned, ms: Math.round(vectorMs * 100) / 100, truncated: vectorResult.truncated },
|
|
321
|
+
fusion: { k: config.search.rrfK, weights, minScore: config.search.minScore, maxPerSource: config.search.maxPerSource },
|
|
322
|
+
},
|
|
323
|
+
elapsedMs,
|
|
324
|
+
mode,
|
|
325
|
+
};
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
/** Fuente por id o URI. */
|
|
329
|
+
export function getSource(db, ref) {
|
|
330
|
+
const row = db.prepare('SELECT * FROM sources WHERE id = ? OR uri = ?').get(ref, ref);
|
|
331
|
+
if (!row) throw new RagError('source-not-found', `no existe la fuente: ${ref}`, { details: { ref } });
|
|
332
|
+
return row;
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
/** Lista de fuentes con filtros y paginación acotada. */
|
|
336
|
+
export function listSources(db, { collection = undefined, tag = undefined, limit = 50, offset = 0 } = {}) {
|
|
337
|
+
const params = [];
|
|
338
|
+
let where = 'WHERE 1 = 1';
|
|
339
|
+
if (collection !== undefined) { where += ' AND s.collection = ?'; params.push(collection); }
|
|
340
|
+
if (tag !== undefined) { where += ' AND EXISTS (SELECT 1 FROM source_tags t WHERE t.source_id = s.id AND t.tag = ?)'; params.push(tag); }
|
|
341
|
+
const total = db.prepare(`SELECT COUNT(*) AS n FROM sources s ${where}`).get(...params).n;
|
|
342
|
+
const rows = db.prepare(`SELECT s.*, (SELECT COUNT(*) FROM chunks c WHERE c.source_id = s.id) AS chunks
|
|
343
|
+
FROM sources s ${where} ORDER BY s.updated_at DESC, s.id ASC LIMIT ? OFFSET ?`).all(...params, limit, offset);
|
|
344
|
+
return { total, rows };
|
|
345
|
+
}
|
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* CR-1 · Selección de proyecto persistida con compare-and-swap.
|
|
3
|
+
*
|
|
4
|
+
* Una sola fila por perfil (`selection_key='profile'`) con una `revision` monotónica. El cliente
|
|
5
|
+
* lee la revisión vigente y la envía de vuelta al escribir: si otro cliente ya escribió, la revisión
|
|
6
|
+
* no coincide y la escritura se rechaza con `revision-conflict` en vez de perder el cambio ajeno
|
|
7
|
+
* (nada de *last write wins*).
|
|
8
|
+
*
|
|
9
|
+
* Qué NO es: no es identidad. La selección no autentica a nadie; el principal lo fija el host y el
|
|
10
|
+
* adaptador lo pasa como `principal`. Un `SessionId` de conversación tampoco sirve como identidad
|
|
11
|
+
* ni como llave de concurrencia.
|
|
12
|
+
*
|
|
13
|
+
* La revisión vive en el registro del perfil, así que sobrevive al cierre de la sesión y al reinicio
|
|
14
|
+
* del proceso. La tabla es aditiva (registro v2) y no toca ninguna fila existente.
|
|
15
|
+
*/
|
|
16
|
+
import { RagError } from './errors.mjs';
|
|
17
|
+
import { appendRegistryAudit, archiveProject } from './registry.mjs';
|
|
18
|
+
import { withTransaction } from './db.mjs';
|
|
19
|
+
|
|
20
|
+
export const SELECTION_KEY = 'profile';
|
|
21
|
+
/** Revisión que declara un cliente que todavía no ha visto ninguna selección. */
|
|
22
|
+
export const NO_SELECTION_REVISION = 0;
|
|
23
|
+
|
|
24
|
+
function rowToSelection(row, projectName = null) {
|
|
25
|
+
if (!row) return null;
|
|
26
|
+
return {
|
|
27
|
+
projectId: row.project_id,
|
|
28
|
+
projectName,
|
|
29
|
+
revision: Number(row.revision),
|
|
30
|
+
source: row.selection_source,
|
|
31
|
+
selectedBy: row.selected_by,
|
|
32
|
+
principal: row.principal,
|
|
33
|
+
selectedAt: Number(row.selected_at),
|
|
34
|
+
updatedAt: Number(row.updated_at),
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/** Selección vigente del perfil, o `null` si nadie ha seleccionado todavía. */
|
|
39
|
+
export function readSelection(db) {
|
|
40
|
+
const row = db.prepare(`SELECT s.selection_key, s.project_id, s.revision, s.selection_source,
|
|
41
|
+
s.selected_by, s.principal, s.selected_at, s.updated_at, p.name AS project_name
|
|
42
|
+
FROM pa_selection s LEFT JOIN projects p ON p.id = s.project_id
|
|
43
|
+
WHERE s.selection_key = ?`).get(SELECTION_KEY);
|
|
44
|
+
return rowToSelection(row, row?.project_name ?? null);
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
function requireProjectForSelection(db, projectId) {
|
|
48
|
+
if (typeof projectId !== 'string' || !projectId.startsWith('prj_')) {
|
|
49
|
+
throw new RagError('invalid-argument', 'projectId no es un identificador de proyecto', {
|
|
50
|
+
details: { reason: 'invalid-field', field: 'project' },
|
|
51
|
+
});
|
|
52
|
+
}
|
|
53
|
+
const project = db.prepare('SELECT id, name, status FROM projects WHERE id = ?').get(projectId);
|
|
54
|
+
if (!project) {
|
|
55
|
+
throw new RagError('project-not-authorized', 'proyecto desconocido o no autorizado', {
|
|
56
|
+
details: { project: projectId },
|
|
57
|
+
});
|
|
58
|
+
}
|
|
59
|
+
if (project.status !== 'active') {
|
|
60
|
+
throw new RagError('project-not-authorized', 'el proyecto está archivado', {
|
|
61
|
+
details: { project: projectId, status: project.status },
|
|
62
|
+
});
|
|
63
|
+
}
|
|
64
|
+
return project;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
function requireExpectedRevision(value) {
|
|
68
|
+
if (value === undefined || value === null) {
|
|
69
|
+
throw new RagError('invalid-argument', 'falta expectedRevision', {
|
|
70
|
+
details: { reason: 'missing-field', field: 'expectedRevision' },
|
|
71
|
+
});
|
|
72
|
+
}
|
|
73
|
+
if (!Number.isInteger(value) || value < NO_SELECTION_REVISION) {
|
|
74
|
+
throw new RagError('invalid-argument', 'expectedRevision inválida', {
|
|
75
|
+
details: { reason: 'invalid-field', field: 'expectedRevision' },
|
|
76
|
+
});
|
|
77
|
+
}
|
|
78
|
+
return value;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* Cambia la selección del perfil si —y sólo si— el cliente conoce la revisión vigente.
|
|
83
|
+
*
|
|
84
|
+
* @returns {{changed: boolean, selection: object}}
|
|
85
|
+
* @throws {RagError} `revision-conflict` (409) si la revisión esperada no es la vigente;
|
|
86
|
+
* `invalid-argument` si falta o no es válida; `project-not-authorized` si el proyecto no sirve.
|
|
87
|
+
*/
|
|
88
|
+
export function applySelection(db, {
|
|
89
|
+
projectId, expectedRevision, selectedBy = 'human', source = 'explicit',
|
|
90
|
+
principal = 'owner', now = Date.now(),
|
|
91
|
+
} = {}) {
|
|
92
|
+
if (!['human', 'host'].includes(selectedBy)) {
|
|
93
|
+
throw new RagError('invalid-argument', 'sólo una persona o el host pueden seleccionar proyecto');
|
|
94
|
+
}
|
|
95
|
+
if (!['explicit', 'cwd'].includes(source)) {
|
|
96
|
+
throw new RagError('invalid-argument', 'origen de selección inválido', { details: { source } });
|
|
97
|
+
}
|
|
98
|
+
const expected = requireExpectedRevision(expectedRevision);
|
|
99
|
+
const project = requireProjectForSelection(db, projectId);
|
|
100
|
+
|
|
101
|
+
return withTransaction(db, () => {
|
|
102
|
+
// `BEGIN IMMEDIATE` serializa a los escritores del perfil: la lectura de la revisión y la
|
|
103
|
+
// escritura ocurren en la misma transacción, así que dos clientes con la misma revisión no
|
|
104
|
+
// pueden confirmar los dos.
|
|
105
|
+
const current = readSelection(db);
|
|
106
|
+
const currentRevision = current ? current.revision : NO_SELECTION_REVISION;
|
|
107
|
+
if (currentRevision !== expected) {
|
|
108
|
+
throw new RagError('revision-conflict', 'la selección cambió mientras la editabas', {
|
|
109
|
+
details: {
|
|
110
|
+
reason: 'revision-mismatch',
|
|
111
|
+
expectedRevision: expected,
|
|
112
|
+
currentRevision,
|
|
113
|
+
current: current
|
|
114
|
+
? { projectId: current.projectId, projectName: current.projectName, revision: current.revision }
|
|
115
|
+
: { projectId: null, projectName: null, revision: NO_SELECTION_REVISION },
|
|
116
|
+
},
|
|
117
|
+
});
|
|
118
|
+
}
|
|
119
|
+
if (current && current.projectId === projectId) {
|
|
120
|
+
// Misma selección y misma revisión: no se crea una revisión nueva por un clic repetido.
|
|
121
|
+
return { changed: false, selection: current };
|
|
122
|
+
}
|
|
123
|
+
const nextRevision = currentRevision + 1;
|
|
124
|
+
if (current) {
|
|
125
|
+
db.prepare(`UPDATE pa_selection
|
|
126
|
+
SET project_id = ?, revision = ?, selection_source = ?, selected_by = ?, principal = ?, updated_at = ?
|
|
127
|
+
WHERE selection_key = ?`)
|
|
128
|
+
.run(projectId, nextRevision, source, selectedBy, principal, now, SELECTION_KEY);
|
|
129
|
+
} else {
|
|
130
|
+
db.prepare(`INSERT INTO pa_selection
|
|
131
|
+
(selection_key, project_id, revision, selection_source, selected_by, principal, selected_at, updated_at)
|
|
132
|
+
VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
|
|
133
|
+
.run(SELECTION_KEY, projectId, nextRevision, source, selectedBy, principal, now, now);
|
|
134
|
+
}
|
|
135
|
+
appendRegistryAudit(db, {
|
|
136
|
+
at: now,
|
|
137
|
+
actor: selectedBy,
|
|
138
|
+
sessionId: null,
|
|
139
|
+
action: current ? 'selection.reselect' : 'selection.select',
|
|
140
|
+
target: projectId,
|
|
141
|
+
outcome: 'ok',
|
|
142
|
+
detail: {
|
|
143
|
+
revision: nextRevision,
|
|
144
|
+
previous: current ? { projectId: current.projectId, revision: current.revision } : null,
|
|
145
|
+
principal,
|
|
146
|
+
},
|
|
147
|
+
});
|
|
148
|
+
return { changed: true, selection: readSelection(db) };
|
|
149
|
+
}, { immediate: true });
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
/* --------------------------------------------------------- reselección al archivar (ACP-07 F1)
|
|
153
|
+
*
|
|
154
|
+
* R-1: un proyecto activo no se archiva sin resolver la selección. Estas dos funciones lo garantizan
|
|
155
|
+
* en una sola transacción: primero se mueve (o se limpia) la selección y después se archiva. Si algo
|
|
156
|
+
* falla, el `ROLLBACK` deja las dos cosas como estaban.
|
|
157
|
+
*/
|
|
158
|
+
|
|
159
|
+
/**
|
|
160
|
+
* Mueve la selección al proyecto activo más antiguo distinto del archivado; si no queda ninguno,
|
|
161
|
+
* deja el perfil sin selección. **Asume que el llamador ya abrió una transacción.**
|
|
162
|
+
*
|
|
163
|
+
* @returns {{changed: boolean, selection: object|null, reason: string}}
|
|
164
|
+
*/
|
|
165
|
+
export function reselectAfterArchive(db, { archivedProjectId, now = Date.now(), principal = 'owner' } = {}) {
|
|
166
|
+
const current = readSelection(db);
|
|
167
|
+
if (!current || current.projectId !== archivedProjectId) {
|
|
168
|
+
return { changed: false, selection: current, reason: 'not-selected' };
|
|
169
|
+
}
|
|
170
|
+
const next = db.prepare(`SELECT id, name FROM projects
|
|
171
|
+
WHERE status = 'active' AND id <> ? ORDER BY created_at, id LIMIT 1`).get(archivedProjectId);
|
|
172
|
+
const nextRevision = current.revision + 1;
|
|
173
|
+
if (next) {
|
|
174
|
+
db.prepare(`UPDATE pa_selection
|
|
175
|
+
SET project_id = ?, revision = ?, selection_source = 'explicit', selected_by = 'host',
|
|
176
|
+
principal = ?, updated_at = ?
|
|
177
|
+
WHERE selection_key = ?`)
|
|
178
|
+
.run(next.id, nextRevision, principal, now, SELECTION_KEY);
|
|
179
|
+
appendRegistryAudit(db, {
|
|
180
|
+
at: now,
|
|
181
|
+
actor: 'host',
|
|
182
|
+
sessionId: null,
|
|
183
|
+
action: 'selection.reselect',
|
|
184
|
+
target: next.id,
|
|
185
|
+
outcome: 'ok',
|
|
186
|
+
detail: {
|
|
187
|
+
reason: 'project-archived',
|
|
188
|
+
revision: nextRevision,
|
|
189
|
+
previous: { projectId: current.projectId, revision: current.revision },
|
|
190
|
+
},
|
|
191
|
+
});
|
|
192
|
+
return { changed: true, selection: readSelection(db), reason: 'moved' };
|
|
193
|
+
}
|
|
194
|
+
// Ni un solo proyecto activo: el perfil se queda sin selección, y el cliente lo verá al releer.
|
|
195
|
+
db.prepare('DELETE FROM pa_selection WHERE selection_key = ?').run(SELECTION_KEY);
|
|
196
|
+
appendRegistryAudit(db, {
|
|
197
|
+
at: now,
|
|
198
|
+
actor: 'host',
|
|
199
|
+
sessionId: null,
|
|
200
|
+
action: 'selection.reselect',
|
|
201
|
+
target: current.projectId,
|
|
202
|
+
outcome: 'ok',
|
|
203
|
+
detail: { reason: 'project-archived', revision: nextRevision, previous: { projectId: current.projectId, revision: current.revision }, next: null },
|
|
204
|
+
});
|
|
205
|
+
return { changed: true, selection: null, reason: 'cleared' };
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/**
|
|
209
|
+
* Archiva un proyecto resolviendo antes la selección, todo en una transacción `IMMEDIATE`.
|
|
210
|
+
* Es la única forma de archivar el proyecto seleccionado: `archiveProject` solo se niega.
|
|
211
|
+
*/
|
|
212
|
+
export function archiveProjectWithSelection(db, {
|
|
213
|
+
projectId, now = Date.now(), actor = 'human', principal = 'owner',
|
|
214
|
+
} = {}) {
|
|
215
|
+
return withTransaction(db, () => {
|
|
216
|
+
const reselect = reselectAfterArchive(db, { archivedProjectId: projectId, now, principal });
|
|
217
|
+
const archived = archiveProject(db, { id: projectId, now, actor });
|
|
218
|
+
return {
|
|
219
|
+
changed: archived.changed,
|
|
220
|
+
project: archived.project,
|
|
221
|
+
selection: reselect.selection,
|
|
222
|
+
selectionChange: reselect.reason,
|
|
223
|
+
};
|
|
224
|
+
}, { immediate: true });
|
|
225
|
+
}
|