@designerbyron/lifecode-rag 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +191 -2
- package/bin/lifecode-rag.mjs +449 -0
- package/client.js +2801 -0
- package/cordis.patch.yml +3 -0
- package/docs/ARCHITECTURE-v0.2.md +269 -0
- package/docs/AUTO-DISCOVERY.md +111 -0
- package/docs/AUTOMATION-POLICIES.md +232 -0
- package/docs/CONTRATO-v0.1.md +195 -0
- package/docs/EMBEDDING-PROVIDERS.md +105 -0
- package/docs/OBSERVABILITY.md +241 -0
- package/docs/PA-UI-0-API-CONTRACT.md +802 -0
- package/docs/PERFORMANCE-BUDGETS.md +118 -0
- package/docs/PROJECT-AWARE-ARCHITECTURE.md +580 -0
- package/docs/PROJECT-AWARE-DATA-CONTRACT.md +411 -0
- package/docs/PROJECT-AWARE-ERROR-CONTRACT.md +112 -0
- package/docs/PROJECT-AWARE-SESSION-CONTRACT.md +120 -0
- package/docs/WORKSPACE-API.md +239 -0
- package/icon.svg +7 -0
- package/index.js +198 -0
- package/lib/audit-export.mjs +70 -0
- package/lib/audit.mjs +120 -0
- package/lib/auto-context.mjs +322 -0
- package/lib/automation.mjs +214 -0
- package/lib/chunk.mjs +100 -0
- package/lib/config-resolve.mjs +119 -0
- package/lib/context.mjs +150 -0
- package/lib/conversation-events.mjs +145 -0
- package/lib/db.mjs +309 -0
- package/lib/diagnose.mjs +197 -0
- package/lib/discovery.mjs +402 -0
- package/lib/doctor.mjs +82 -0
- package/lib/embed.mjs +96 -0
- package/lib/embedders.mjs +103 -0
- package/lib/errors.mjs +227 -0
- package/lib/exec-context.mjs +238 -0
- package/lib/extract.mjs +260 -0
- package/lib/harness-workspaces.mjs +85 -0
- package/lib/hash.mjs +34 -0
- package/lib/ingest.mjs +239 -0
- package/lib/inputs.mjs +67 -0
- package/lib/library-state.mjs +252 -0
- package/lib/maintenance.mjs +113 -0
- package/lib/metrics.mjs +164 -0
- package/lib/migrate.mjs +373 -0
- package/lib/operations.mjs +132 -0
- package/lib/pa-api.mjs +517 -0
- package/lib/paths.mjs +345 -0
- package/lib/policy.mjs +125 -0
- package/lib/profile.mjs +128 -0
- package/lib/readmodel.mjs +159 -0
- package/lib/recovery.mjs +557 -0
- package/lib/registry-schema.mjs +206 -0
- package/lib/registry.mjs +406 -0
- package/lib/resolve.mjs +311 -0
- package/lib/retention.mjs +143 -0
- package/lib/revocation.mjs +124 -0
- package/lib/roots-structure.mjs +224 -0
- package/lib/schema.mjs +173 -0
- package/lib/scope-ops.mjs +379 -0
- package/lib/scope-stores.mjs +128 -0
- package/lib/search.mjs +345 -0
- package/lib/selection.mjs +150 -0
- package/lib/server.mjs +335 -0
- package/lib/session-identity.mjs +51 -0
- package/lib/sessions.mjs +343 -0
- package/lib/sync-scheduler.mjs +354 -0
- package/lib/sync.mjs +755 -0
- package/lib/tags.mjs +45 -0
- package/lib/tools.mjs +364 -0
- package/lib/trusted-roots.mjs +149 -0
- package/lib/worker-context.mjs +22 -0
- package/package.json +67 -5
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Resolución de configuración de LifeCode RAG (LE-RAG-01 · Fase 2).
|
|
3
|
+
*
|
|
4
|
+
* Precedencia **por clave**: perfil > global > defaults. Una sola validación sobre la mezcla,
|
|
5
|
+
* de modo que el resultado es idéntico al que aplican las herramientas.
|
|
6
|
+
*
|
|
7
|
+
* El core no depende de DSH: la raíz de datos se puede fijar con `LIFECODE_RAG_DATA` y el perfil
|
|
8
|
+
* con `LIFECODE_RAG_PROFILE`. Si no se indican, se conserva la raíz histórica (compatibilidad).
|
|
9
|
+
*
|
|
10
|
+
* <dataRoot>/config.json configuración global (opcional)
|
|
11
|
+
* <dataRoot>/profiles/<profileKey>/config.json configuración de perfil (opcional)
|
|
12
|
+
*
|
|
13
|
+
* Un fichero existente e inválido **falla en cerrado** (`invalid-config`) con la ruta en `details`;
|
|
14
|
+
* nunca se cae en silencio a los defaults.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
import { existsSync, readFileSync } from 'node:fs';
|
|
18
|
+
import { join } from 'node:path';
|
|
19
|
+
|
|
20
|
+
import { RagError } from './errors.mjs';
|
|
21
|
+
import { ragRoot, validateConfig } from './paths.mjs';
|
|
22
|
+
import { profileKey as legacyProfileKey } from './profile.mjs';
|
|
23
|
+
|
|
24
|
+
export const DATA_ROOT_ENV = 'LIFECODE_RAG_DATA';
|
|
25
|
+
export const PROFILE_ENV = 'LIFECODE_RAG_PROFILE';
|
|
26
|
+
|
|
27
|
+
/** Raíz de datos propia; si no se declara, la histórica del home (compatibilidad). */
|
|
28
|
+
export function resolveDataRoot(env = process.env) {
|
|
29
|
+
const own = env?.[DATA_ROOT_ENV];
|
|
30
|
+
if (typeof own === 'string' && own.trim() !== '') return own.trim();
|
|
31
|
+
return ragRoot(env);
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** Perfil propio; si no se declara, el histórico (nombre del perfil del host). */
|
|
35
|
+
export function resolveProfileKey(env = process.env) {
|
|
36
|
+
const own = env?.[PROFILE_ENV];
|
|
37
|
+
if (typeof own === 'string' && own.trim() !== '') return own.trim();
|
|
38
|
+
return legacyProfileKey(env);
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
export function configFilePaths({ dataRoot, profileKey }) {
|
|
42
|
+
if (typeof dataRoot !== 'string' || dataRoot.trim() === '') {
|
|
43
|
+
throw new RagError('invalid-config', 'falta la raíz de datos para resolver la configuración');
|
|
44
|
+
}
|
|
45
|
+
if (typeof profileKey !== 'string' || profileKey.trim() === '') {
|
|
46
|
+
throw new RagError('invalid-config', 'falta el perfil para resolver la configuración');
|
|
47
|
+
}
|
|
48
|
+
return {
|
|
49
|
+
global: join(dataRoot, 'config.json'),
|
|
50
|
+
profile: join(dataRoot, 'profiles', profileKey, 'config.json'),
|
|
51
|
+
};
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
function isPlainObject(value) {
|
|
55
|
+
return value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/** Lectura estricta de una capa: ausente = null; ilegible o no-objeto = `invalid-config`. */
|
|
59
|
+
export function readConfigLayer(path) {
|
|
60
|
+
if (!existsSync(path)) return { path, exists: false, value: null };
|
|
61
|
+
let text;
|
|
62
|
+
try {
|
|
63
|
+
text = readFileSync(path, 'utf8');
|
|
64
|
+
} catch (error) {
|
|
65
|
+
throw new RagError('invalid-config', 'no se pudo leer la configuración', { details: { path }, cause: error });
|
|
66
|
+
}
|
|
67
|
+
let parsed;
|
|
68
|
+
try {
|
|
69
|
+
parsed = JSON.parse(text);
|
|
70
|
+
} catch (error) {
|
|
71
|
+
throw new RagError('invalid-config', 'la configuración no es JSON válido', { details: { path }, cause: error });
|
|
72
|
+
}
|
|
73
|
+
if (!isPlainObject(parsed)) {
|
|
74
|
+
throw new RagError('invalid-config', 'la configuración debe ser un objeto JSON', { details: { path } });
|
|
75
|
+
}
|
|
76
|
+
return { path, exists: true, value: parsed };
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/** Mezcla por clave, en orden de menor a mayor prioridad. Sólo fusiona objetos planos de primer nivel. */
|
|
80
|
+
export function mergeLayers(...layers) {
|
|
81
|
+
const out = {};
|
|
82
|
+
for (const layer of layers) {
|
|
83
|
+
if (!isPlainObject(layer)) continue;
|
|
84
|
+
for (const [key, value] of Object.entries(layer)) {
|
|
85
|
+
out[key] = isPlainObject(out[key]) && isPlainObject(value) ? { ...out[key], ...value } : value;
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
return out;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* Resuelve la configuración efectiva.
|
|
93
|
+
* @returns {{config: object, sources: {global: boolean, profile: boolean}, paths: object, dataRoot: string, profileKey: string}}
|
|
94
|
+
*/
|
|
95
|
+
export function resolveConfig({ dataRoot, profileKey } = {}) {
|
|
96
|
+
const paths = configFilePaths({ dataRoot, profileKey });
|
|
97
|
+
const global = readConfigLayer(paths.global);
|
|
98
|
+
const profile = readConfigLayer(paths.profile);
|
|
99
|
+
const merged = mergeLayers(global.value, profile.value);
|
|
100
|
+
let config;
|
|
101
|
+
try {
|
|
102
|
+
config = validateConfig(merged);
|
|
103
|
+
} catch (error) {
|
|
104
|
+
// Se reetiqueta con las rutas implicadas; el mensaje original no contiene valores sensibles.
|
|
105
|
+
throw new RagError('invalid-config', error?.message ?? 'configuración inválida', {
|
|
106
|
+
details: {
|
|
107
|
+
global: global.exists ? paths.global : null,
|
|
108
|
+
profile: profile.exists ? paths.profile : null,
|
|
109
|
+
},
|
|
110
|
+
cause: error,
|
|
111
|
+
});
|
|
112
|
+
}
|
|
113
|
+
return { config, sources: { global: global.exists, profile: profile.exists }, paths, dataRoot, profileKey };
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/** Atajo para consumidores que sólo necesitan la configuración. */
|
|
117
|
+
export function effectiveConfig(env = process.env) {
|
|
118
|
+
return resolveConfig({ dataRoot: resolveDataRoot(env), profileKey: resolveProfileKey(env) });
|
|
119
|
+
}
|
package/lib/context.mjs
ADDED
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Ensamblado de contexto v0.2 (M1): diversidad MMR, deduplicación, presupuesto y citas verificables.
|
|
3
|
+
*
|
|
4
|
+
* Cada entrada lleva su `chunk_key` y el rango de caracteres en la fuente; un `[n]` del texto resuelve
|
|
5
|
+
* contra `citations[n-1]`. El presupuesto se mide en tokens **estimados** (4 caracteres por token), y así
|
|
6
|
+
* se declara; no se presenta como medición exacta.
|
|
7
|
+
*
|
|
8
|
+
* Dos entradas: `assembleContext` (síncrona, con vectores locales; compatible con v0.1) y
|
|
9
|
+
* `assembleContextAsync` (usa el proveedor configurado, que puede ser remoto).
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
import { embedText, cosine } from './embed.mjs';
|
|
13
|
+
import { RagError } from './errors.mjs';
|
|
14
|
+
|
|
15
|
+
export function estimateTokens(text) {
|
|
16
|
+
return Math.ceil(String(text).length / 4);
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
function headerFor(index, chunk) {
|
|
20
|
+
const section = chunk.heading ? ` › ${chunk.heading}` : '';
|
|
21
|
+
return `[${index + 1}] ${chunk.sourceTitle || chunk.title}${section}\n`;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
function normalizeForDedupe(text) {
|
|
25
|
+
return String(text).normalize('NFC').toLowerCase().replace(/\s+/gu, ' ').trim();
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Núcleo síncrono: recibe los vectores ya calculados por `chunkKey`.
|
|
30
|
+
* @returns {{text:string, citations:Array, tokens:number, truncated:boolean, considered:number, deduped:number}}
|
|
31
|
+
*/
|
|
32
|
+
export function assembleContextWithVectors({
|
|
33
|
+
results, config, budgetTokens = undefined, maxChunks = undefined, mmrLambda = undefined, vectors = undefined,
|
|
34
|
+
}) {
|
|
35
|
+
if (!Array.isArray(results)) throw new RagError('internal', 'assembleContext espera resultados');
|
|
36
|
+
const budget = budgetTokens ?? config.context.budgetTokens;
|
|
37
|
+
const limit = Math.min(maxChunks ?? config.context.maxChunks, config.context.maxChunks);
|
|
38
|
+
const lambda = mmrLambda ?? config.context.mmrLambda;
|
|
39
|
+
if (!(budget > 0) || !(limit > 0)) throw new RagError('invalid-argument', 'presupuesto de contexto inválido');
|
|
40
|
+
|
|
41
|
+
const seenText = new Set();
|
|
42
|
+
const seenRange = new Set();
|
|
43
|
+
const candidates = [];
|
|
44
|
+
let deduped = 0;
|
|
45
|
+
for (const row of results) {
|
|
46
|
+
if (!row || typeof row.text !== 'string' || row.text === '') continue;
|
|
47
|
+
const key = normalizeForDedupe(row.text);
|
|
48
|
+
const range = `${row.sourceId}:${row.charStart}-${row.charEnd}`;
|
|
49
|
+
if (seenText.has(key) || seenRange.has(range)) { deduped += 1; continue; }
|
|
50
|
+
seenText.add(key);
|
|
51
|
+
seenRange.add(range);
|
|
52
|
+
candidates.push(row);
|
|
53
|
+
}
|
|
54
|
+
if (candidates.length === 0) {
|
|
55
|
+
return { text: '', citations: [], tokens: 0, truncated: false, considered: 0, deduped };
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
const vectorMap = vectors ?? new Map(candidates.map((row) => [row.chunkKey, embedText(row.text, config.embedding)]));
|
|
59
|
+
const maxScore = Math.max(...candidates.map((row) => row.score ?? row.rrf ?? 0), Number.EPSILON);
|
|
60
|
+
const relevance = (row) => (row.score ?? row.rrf ?? 0) / maxScore;
|
|
61
|
+
|
|
62
|
+
const pool = [...candidates];
|
|
63
|
+
const selected = [];
|
|
64
|
+
let tokens = 0;
|
|
65
|
+
|
|
66
|
+
while (pool.length > 0 && selected.length < limit) {
|
|
67
|
+
let bestIndex = -1;
|
|
68
|
+
let bestValue = -Infinity;
|
|
69
|
+
for (let i = 0; i < pool.length; i += 1) {
|
|
70
|
+
const row = pool[i];
|
|
71
|
+
let penalty = 0;
|
|
72
|
+
for (const chosen of selected) {
|
|
73
|
+
const a = vectorMap.get(row.chunkKey);
|
|
74
|
+
const b = vectorMap.get(chosen.chunkKey);
|
|
75
|
+
if (a && b) penalty = Math.max(penalty, cosine(a, b));
|
|
76
|
+
}
|
|
77
|
+
const value = lambda * relevance(row) - (1 - lambda) * penalty;
|
|
78
|
+
if (value > bestValue) { bestValue = value; bestIndex = i; }
|
|
79
|
+
}
|
|
80
|
+
if (bestIndex < 0) break;
|
|
81
|
+
const [candidate] = pool.splice(bestIndex, 1);
|
|
82
|
+
|
|
83
|
+
const index = selected.length;
|
|
84
|
+
const block = `${headerFor(index, candidate)}${candidate.text}`;
|
|
85
|
+
const cost = estimateTokens(block) + 1;
|
|
86
|
+
if (tokens + cost > budget) {
|
|
87
|
+
if (selected.length === 0) {
|
|
88
|
+
return { text: '', citations: [], tokens: 0, truncated: true, considered: candidates.length, deduped };
|
|
89
|
+
}
|
|
90
|
+
break;
|
|
91
|
+
}
|
|
92
|
+
selected.push(candidate);
|
|
93
|
+
tokens += cost;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
// Todas las claves se declaran siempre con un valor definido: una propiedad `undefined` hace que el
|
|
97
|
+
// objeto no sobreviva a una ida y vuelta por JSON (`JSON.stringify` la omite) y el host rechaza el
|
|
98
|
+
// resultado de la herramienta con «value is not lossless JSON». Observado en el perfil real con
|
|
99
|
+
// citas de fuentes distintas (M6.5).
|
|
100
|
+
const citations = selected.map((chunk, index) => ({
|
|
101
|
+
n: index + 1,
|
|
102
|
+
chunkKey: chunk.chunkKey ?? null,
|
|
103
|
+
sourceId: chunk.sourceId ?? chunk.source_id ?? null,
|
|
104
|
+
uri: chunk.uri ?? null,
|
|
105
|
+
title: chunk.sourceTitle ?? chunk.title ?? null,
|
|
106
|
+
heading: chunk.heading ?? null,
|
|
107
|
+
ordinal: chunk.ordinal ?? null,
|
|
108
|
+
charStart: chunk.charStart ?? null,
|
|
109
|
+
charEnd: chunk.charEnd ?? null,
|
|
110
|
+
score: chunk.score ?? null,
|
|
111
|
+
}));
|
|
112
|
+
|
|
113
|
+
const text = selected.map((chunk, index) => `${headerFor(index, chunk)}${chunk.text ?? ''}`).join('\n\n');
|
|
114
|
+
return {
|
|
115
|
+
text,
|
|
116
|
+
citations,
|
|
117
|
+
tokens,
|
|
118
|
+
truncated: selected.length < candidates.length,
|
|
119
|
+
considered: candidates.length,
|
|
120
|
+
deduped,
|
|
121
|
+
};
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/** Compatibilidad v0.1: MMR con embeddings locales. */
|
|
125
|
+
export function assembleContext(options = {}) {
|
|
126
|
+
return assembleContextWithVectors(options);
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* Igual que la anterior, pero los vectores vienen del proveedor configurado (posible remoto).
|
|
131
|
+
*
|
|
132
|
+
* Sin embedder —el camino automático no tiene canal de aprobación para egresar— se usan vectores
|
|
133
|
+
* locales sólo para la diversidad de MMR: es cálculo puro, no una llamada a un tercero.
|
|
134
|
+
*/
|
|
135
|
+
export async function assembleContextAsync({ results, config, embedder, ...options } = {}) {
|
|
136
|
+
if (!Array.isArray(results)) throw new RagError('internal', 'assembleContextAsync espera resultados');
|
|
137
|
+
const candidates = results.filter((row) => row && typeof row.text === 'string' && row.text !== '');
|
|
138
|
+
const vectors = new Map();
|
|
139
|
+
if (candidates.length > 0) {
|
|
140
|
+
if (embedder && typeof embedder.embed === 'function') {
|
|
141
|
+
const embedded = await embedder.embed(candidates.map((row) => row.text));
|
|
142
|
+
candidates.forEach((row, index) => vectors.set(row.chunkKey, embedded[index]));
|
|
143
|
+
} else {
|
|
144
|
+
// MMR con vectores locales aunque el proveedor configurado sea remoto: aquí no se egresa.
|
|
145
|
+
const localEmbedding = { ...(config?.embedding ?? {}), provider: 'local-hash-v1' };
|
|
146
|
+
for (const row of candidates) vectors.set(row.chunkKey, embedText(row.text, localEmbedding));
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
return assembleContextWithVectors({ results, config, vectors, ...options });
|
|
150
|
+
}
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Contrato interno de eventos de conversación (LE-RAG-01 · Fase 5).
|
|
3
|
+
*
|
|
4
|
+
* Diseño, no integración: define la forma canónica que **cualquier host** puede entregar mediante un
|
|
5
|
+
* adaptador. No importa nada del host y no se conecta a eventos reales.
|
|
6
|
+
*
|
|
7
|
+
* Reglas:
|
|
8
|
+
* - Sólo se aceptan mensajes (`message`) con rol `user`, `assistant` o `tool`.
|
|
9
|
+
* - Se rechazan roles internos (`system`, `reasoning`) y tipos desconocidos.
|
|
10
|
+
* - `eventId` es la clave de idempotencia: el mismo evento aplicado dos veces no cambia nada.
|
|
11
|
+
* - `sequence` ordena; dos eventos distintos con la misma secuencia → `sequence-conflict`.
|
|
12
|
+
* - `replace` sustituye el contenido de un evento existente sin cambiar su secuencia.
|
|
13
|
+
* - `delete` elimina un evento.
|
|
14
|
+
* - `metadata` se filtra: nunca se conservan claves con pinta de secreto.
|
|
15
|
+
* - La reducción es pura; el cursor lo decide quien la llama.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
import { RagError } from './errors.mjs';
|
|
19
|
+
|
|
20
|
+
export const EVENT_ROLES = Object.freeze(['user', 'assistant', 'tool']);
|
|
21
|
+
export const EVENT_OPERATIONS = Object.freeze(['append', 'replace', 'delete']);
|
|
22
|
+
const FORBIDDEN_ROLES = Object.freeze(['system', 'reasoning', 'developer']);
|
|
23
|
+
const SECRET_KEY = /(api[_-]?key|authorization|bearer|secret|password|token|cookie|credential)/i;
|
|
24
|
+
|
|
25
|
+
function fail(message, details = {}) {
|
|
26
|
+
throw new RagError('invalid-argument', message, { details });
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
function cleanMetadata(metadata) {
|
|
30
|
+
if (metadata === undefined || metadata === null) return {};
|
|
31
|
+
if (typeof metadata !== 'object' || Array.isArray(metadata)) fail('metadata debe ser un objeto');
|
|
32
|
+
const out = {};
|
|
33
|
+
for (const [key, value] of Object.entries(metadata)) {
|
|
34
|
+
if (SECRET_KEY.test(key)) continue;
|
|
35
|
+
if (value === null || ['string', 'number', 'boolean'].includes(typeof value)) out[key] = value;
|
|
36
|
+
}
|
|
37
|
+
return out;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** Valida y normaliza un evento crudo. Lanza `invalid-argument` si no es utilizable. */
|
|
41
|
+
export function normalizeEvent(raw) {
|
|
42
|
+
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) fail('el evento debe ser un objeto');
|
|
43
|
+
const { eventId, conversationId, sequence, role, content } = raw;
|
|
44
|
+
if (typeof eventId !== 'string' || eventId.trim() === '') fail('eventId obligatorio', { field: 'eventId' });
|
|
45
|
+
if (typeof conversationId !== 'string' || conversationId.trim() === '') fail('conversationId obligatorio', { field: 'conversationId' });
|
|
46
|
+
if (!Number.isInteger(sequence) || sequence < 0) fail('sequence debe ser un entero ≥ 0', { field: 'sequence' });
|
|
47
|
+
if (FORBIDDEN_ROLES.includes(role)) fail('rol no indexable', { field: 'role', role });
|
|
48
|
+
if (!EVENT_ROLES.includes(role)) fail('rol desconocido', { field: 'role', role: role ?? null });
|
|
49
|
+
const operation = raw.operation ?? 'append';
|
|
50
|
+
if (operation !== 'delete' && (typeof content !== 'string' || content.trim() === '')) {
|
|
51
|
+
fail('content obligatorio', { field: 'content' });
|
|
52
|
+
}
|
|
53
|
+
if (!EVENT_OPERATIONS.includes(operation)) fail('operación desconocida', { field: 'operation', operation });
|
|
54
|
+
const timestamp = raw.timestamp === undefined ? null : raw.timestamp;
|
|
55
|
+
if (timestamp !== null && !Number.isFinite(timestamp)) fail('timestamp debe ser numérico', { field: 'timestamp' });
|
|
56
|
+
return {
|
|
57
|
+
eventId,
|
|
58
|
+
conversationId,
|
|
59
|
+
sequence,
|
|
60
|
+
role,
|
|
61
|
+
content,
|
|
62
|
+
operation,
|
|
63
|
+
timestamp,
|
|
64
|
+
metadata: cleanMetadata(raw.metadata),
|
|
65
|
+
};
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Reduce una lista de eventos a los mensajes vigentes.
|
|
70
|
+
* @returns {{messages: Array, applied: number, dropped: number, lastSequence: number, cursor: string|null}}
|
|
71
|
+
*/
|
|
72
|
+
export function reduceConversation(events, { cursor = null, maxEvents = 5000 } = {}) {
|
|
73
|
+
if (!Array.isArray(events)) fail('events debe ser un array');
|
|
74
|
+
const normalized = events.map(normalizeEvent);
|
|
75
|
+
const conversationId = normalized[0]?.conversationId ?? null;
|
|
76
|
+
if (normalized.some((event) => event.conversationId !== conversationId)) {
|
|
77
|
+
fail('todos los eventos deben pertenecer a la misma conversación');
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
const seenSequence = new Map();
|
|
81
|
+
for (const event of normalized) {
|
|
82
|
+
const other = seenSequence.get(event.sequence);
|
|
83
|
+
if (other && other !== event.eventId) {
|
|
84
|
+
throw new RagError('sequence-conflict', 'dos eventos distintos comparten secuencia', {
|
|
85
|
+
details: { sequence: event.sequence, eventId: event.eventId, other },
|
|
86
|
+
});
|
|
87
|
+
}
|
|
88
|
+
seenSequence.set(event.sequence, event.eventId);
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
const ordered = [...normalized].sort((a, b) => a.sequence - b.sequence);
|
|
92
|
+
const from = Number.isInteger(cursor) ? cursor : -1;
|
|
93
|
+
const state = new Map();
|
|
94
|
+
const applied = new Map();
|
|
95
|
+
let applications = 0;
|
|
96
|
+
let dropped = 0;
|
|
97
|
+
let lastSequence = from;
|
|
98
|
+
for (const event of ordered) {
|
|
99
|
+
lastSequence = Math.max(lastSequence, event.sequence);
|
|
100
|
+
if (event.sequence <= from) { dropped += 1; continue; }
|
|
101
|
+
if (event.operation === 'delete') {
|
|
102
|
+
state.delete(event.eventId);
|
|
103
|
+
applied.delete(event.eventId);
|
|
104
|
+
dropped += 1;
|
|
105
|
+
continue;
|
|
106
|
+
}
|
|
107
|
+
const before = applied.get(event.eventId);
|
|
108
|
+
if (before && before.content === event.content && before.operation === event.operation) {
|
|
109
|
+
dropped += 1; // idempotencia: el mismo evento otra vez no cambia nada
|
|
110
|
+
continue;
|
|
111
|
+
}
|
|
112
|
+
if (event.operation === 'append' && state.has(event.eventId)) {
|
|
113
|
+
const current = state.get(event.eventId);
|
|
114
|
+
if (current.content !== event.content) {
|
|
115
|
+
fail('append sobre un evento existente con otro contenido; usa replace', { eventId: event.eventId });
|
|
116
|
+
}
|
|
117
|
+
dropped += 1;
|
|
118
|
+
continue;
|
|
119
|
+
}
|
|
120
|
+
if (event.operation === 'replace') {
|
|
121
|
+
const current = state.get(event.eventId);
|
|
122
|
+
if (!current) fail('replace sobre un evento desconocido', { eventId: event.eventId });
|
|
123
|
+
// El reemplazo cambia el contenido, no la posición: se conserva la secuencia original.
|
|
124
|
+
state.set(event.eventId, { ...event, sequence: current.sequence });
|
|
125
|
+
applied.set(event.eventId, { content: event.content, operation: event.operation });
|
|
126
|
+
applications += 1;
|
|
127
|
+
continue;
|
|
128
|
+
}
|
|
129
|
+
state.set(event.eventId, event);
|
|
130
|
+
applied.set(event.eventId, { content: event.content, operation: event.operation });
|
|
131
|
+
applications += 1;
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
let messages = [...state.values()].sort((a, b) => a.sequence - b.sequence);
|
|
135
|
+
if (Number.isInteger(maxEvents) && maxEvents > 0 && messages.length > maxEvents) {
|
|
136
|
+
messages = messages.slice(messages.length - maxEvents);
|
|
137
|
+
}
|
|
138
|
+
return {
|
|
139
|
+
messages: messages.map(({ eventId, role, content, sequence, timestamp }) => ({ eventId, role, content, sequence, timestamp })),
|
|
140
|
+
applied: applications,
|
|
141
|
+
dropped,
|
|
142
|
+
lastSequence,
|
|
143
|
+
cursor: lastSequence,
|
|
144
|
+
};
|
|
145
|
+
}
|