@saulwade/swl-ses 2.6.1 → 2.8.0

package/scripts/lib/approval-receipts.js

@@ -0,0 +1,190 @@
+'use strict';
+
+/** Verifica approvals Ed25519 ligadas a principal, operación, PLAN y FSM. */
+
+const crypto = require('node:crypto');
+
+const { assertPrincipalCurrent, isVerifiedPrincipal } = require('./principal-verifier');
+const {
+  exactKeys, fail, freezeDeep, getContractValidators, plainObject,
+} = require('./policy-verifier-utils');
+const signed = require('./signed-envelope');
+
+const APPROVALS = new WeakSet();
+const APPROVAL_META = new WeakMap();
+const SHA256 = /^[a-f0-9]{64}$/u;
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
+const CLAIM_KEYS = [
+  'kind', 'schemaVersion', 'approvalId', 'principalDigest', 'operationDigest',
+  'sessionId', 'runtimeId', 'projectId', 'worktreeDigest', 'capability', 'effectKind',
+  'scopeDigest', 'planDigest', 'fsmVersion', 'issuedAt', 'expiresAt', 'nonce',
+];
+const SCOPED_CLAIM_KEYS = [...CLAIM_KEYS, 'phaseId', 'taskId'];
+const EPOCH_CLAIM_KEYS = [...SCOPED_CLAIM_KEYS, 'g1ApprovalDigest'];
+const OPTION_KEYS = [
+  'trustContext', 'dependencies', 'principal', 'operation', 'planDigest', 'fsmVersion',
+];
+const SCOPED_OPTION_KEYS = [...OPTION_KEYS, 'phaseId', 'taskId'];
+const EPOCH_OPTION_KEYS = [...SCOPED_OPTION_KEYS, 'g1ApprovalDigest'];
+const TASK = /^T-[0-9]{2}$/u;
+
+function validateOptions(options) {
+  const contract = getContractValidators();
+  plainObject(options, 'APPROVAL_OPTIONS_INVALID', 'opciones approval');
+  const isScoped = Object.hasOwn(options, 'phaseId') || Object.hasOwn(options, 'taskId');
+  const hasEpoch = Object.hasOwn(options, 'g1ApprovalDigest');
+  exactKeys(
+    options, hasEpoch ? EPOCH_OPTION_KEYS : (isScoped ? SCOPED_OPTION_KEYS : OPTION_KEYS),
+    'APPROVAL_OPTIONS_INVALID', 'opciones approval'
+  );
+  if (!contract.isKernelDependencies(options.dependencies)) {
+    fail('APPROVAL_OPTIONS_INVALID', 'dependencies inválidas');
+  }
+  if (!isVerifiedPrincipal(options.principal)) {
+    fail('APPROVAL_PRINCIPAL_INVALID', 'principal inválido');
+  }
+  if (!contract.isVerifiedOperation(options.operation)) {
+    fail('APPROVAL_OPERATION_INVALID', 'operación inválida');
+  }
+  if (!SHA256.test(options.planDigest) || !Number.isInteger(options.fsmVersion)
+      || options.fsmVersion < 0) {
+    fail('APPROVAL_OPTIONS_INVALID', 'PLAN o FSM inválido');
+  }
+  if (isScoped && (!IDENTIFIER.test(options.phaseId) || !TASK.test(options.taskId))) {
+    fail('APPROVAL_OPTIONS_INVALID', 'alcance de gate inválido');
+  }
+  if (hasEpoch && !SHA256.test(options.g1ApprovalDigest)) {
+    fail('APPROVAL_OPTIONS_INVALID', 'época G1 inválida');
+  }
+}
+
+function validateShape(claims) {
+  plainObject(claims, 'APPROVAL_INVALID', 'claims approval');
+  const isScoped = ['1.1.0', '1.2.0'].includes(claims.schemaVersion);
+  const keys = claims.schemaVersion === '1.2.0' ? EPOCH_CLAIM_KEYS
+    : (isScoped ? SCOPED_CLAIM_KEYS : CLAIM_KEYS);
+  exactKeys(claims, keys,
+    'APPROVAL_INVALID', 'claims approval');
+  if (claims.kind !== 'authorization-approval'
+      || !['1.0.0', '1.1.0', '1.2.0'].includes(claims.schemaVersion)) {
+    fail('APPROVAL_INVALID', 'approval futura o inválida');
+  }
+  for (const field of ['approvalId', 'sessionId', 'runtimeId', 'projectId', 'nonce']) {
+    if (!IDENTIFIER.test(claims[field])) fail('APPROVAL_INVALID', `${field} inválido`);
+  }
+  for (const field of ['principalDigest', 'operationDigest', 'worktreeDigest',
+    'scopeDigest', 'planDigest']) {
+    if (!SHA256.test(claims[field])) fail('APPROVAL_INVALID', `${field} inválido`);
+  }
+  if (!IDENTIFIER.test(claims.capability) || !IDENTIFIER.test(claims.effectKind)
+      || !Number.isInteger(claims.fsmVersion) || claims.fsmVersion < 0) {
+    fail('APPROVAL_INVALID', 'capability, effect o FSM inválido');
+  }
+  if (isScoped && (!IDENTIFIER.test(claims.phaseId) || !TASK.test(claims.taskId))) {
+    fail('APPROVAL_INVALID', 'alcance de gate inválido');
+  }
+  if (claims.schemaVersion === '1.2.0' && !SHA256.test(claims.g1ApprovalDigest)) {
+    fail('APPROVAL_INVALID', 'época G1 inválida');
+  }
+}
+
+function validateBindings(claims, options) {
+  const requestedSchema = Object.hasOwn(options, 'g1ApprovalDigest') ? '1.2.0'
+    : (Object.hasOwn(options, 'phaseId') ? '1.1.0' : '1.0.0');
+  if (claims.schemaVersion !== requestedSchema) {
+    fail('APPROVAL_BINDING_INVALID', 'schema no satisface las garantías solicitadas');
+  }
+  const expected = {
+    principalDigest: options.principal.principalDigest,
+    operationDigest: options.operation.operationDigest,
+    sessionId: options.principal.sessionId, runtimeId: options.principal.runtimeId,
+    projectId: options.principal.projectId, worktreeDigest: options.principal.worktreeDigest,
+    capability: options.operation.capability, effectKind: options.operation.effectKind,
+    scopeDigest: options.operation.scope.digest, planDigest: options.planDigest,
+    fsmVersion: options.fsmVersion,
+  };
+  if (['1.1.0', '1.2.0'].includes(requestedSchema)) {
+    expected.phaseId = options.phaseId;
+    expected.taskId = options.taskId;
+  }
+  if (requestedSchema === '1.2.0') {
+    expected.g1ApprovalDigest = options.g1ApprovalDigest;
+  }
+  if (Object.entries(expected).some(([key, value]) => claims[key] !== value)) {
+    fail('APPROVAL_BINDING_INVALID', 'approval ligada a otro contexto');
+  }
+}
+
+function validateTime(claims, now) {
+  signed.validarTimestampIso(claims.issuedAt, 'approval issuedAt');
+  signed.validarTimestampIso(claims.expiresAt, 'approval expiresAt');
+  if (claims.issuedAt > now || claims.expiresAt < now || claims.issuedAt >= claims.expiresAt) {
+    fail('APPROVAL_EXPIRED', 'approval fuera de vigencia');
+  }
+}
+
+function createReceipt(envelope, options) {
+  const digestInput = {
+    issuer: envelope.issuer, subject: envelope.subject,
+    signerPublicKeyDigest: envelope.signerPublicKeyDigest,
+    trustEpoch: envelope.trustEpoch, trustDigest: envelope.trustDigest,
+    claims: envelope.claims,
+  };
+  const approvalDigest = crypto.createHash('sha256')
+    .update(signed.canonicalizarIJson(digestInput), 'utf8').digest('hex');
+  const receipt = freezeDeep({
+    kind: 'verified-approval', ...structuredClone(envelope.claims),
+    approverId: envelope.subject, issuer: envelope.issuer,
+    keyId: envelope.keyId, rootKeyDigest: envelope.rootKeyDigest,
+    signerPublicKeyDigest: envelope.signerPublicKeyDigest,
+    trustEpoch: envelope.trustEpoch, trustDigest: envelope.trustDigest,
+    approvalDigest,
+  });
+  APPROVALS.add(receipt);
+  APPROVAL_META.set(receipt, Object.freeze({
+    envelope, principal: options.principal,
+    integrityLedger: options.dependencies.integrityLedger,
+  }));
+  return receipt;
+}
+
+function assertApprovalCurrent(approval, authority) {
+  if (!APPROVALS.has(approval)) fail('APPROVAL_INVALID', 'approval no verificada');
+  const metadata = APPROVAL_META.get(approval);
+  if (!metadata.integrityLedger.isAuthorityReceipt(authority)) {
+    fail('APPROVAL_AUTHORITY_INVALID', 'autoridad no verificada');
+  }
+  assertPrincipalCurrent(metadata.principal, authority);
+  signed.revalidarEnvelopeVerificado(metadata.envelope, authority.observedAt);
+  validateTime(approval, authority.observedAt);
+  return true;
+}
+
+function verifyApproval(rawBytes, options) {
+  validateOptions(options);
+  const authority = options.dependencies.integrityLedger.readAuthority();
+  const envelope = signed.verificarEnvelope(rawBytes, {
+    trustContext: options.trustContext, expectedType: 'approval',
+    requiredScope: `approve:${options.operation.capability}`, now: authority.observedAt,
+  });
+  if (envelope.trustEpoch !== authority.trustEpoch
+      || envelope.trustDigest !== authority.trustDigest
+      || envelope.rootKeyDigest !== authority.rootKeyDigest) {
+    fail('APPROVAL_TRUST_INVALID', 'approval ligada a trust distinto');
+  }
+  assertPrincipalCurrent(options.principal, authority);
+  validateShape(envelope.claims);
+  validateBindings(envelope.claims, options);
+  validateTime(envelope.claims, authority.observedAt);
+  return createReceipt(envelope, options);
+}
+
+function isVerifiedApproval(value) {
+  return APPROVALS.has(value);
+}
+
+module.exports = {
+  assertApprovalCurrent,
+  isVerifiedApproval,
+  verifyApproval,
+};

package/scripts/lib/artefactos-python.js

@@ -1,43 +1,43 @@
-'use strict';
-
-/**
- * artefactos-python.js — fuente única de verdad para los artefactos
- * Python que NO deben distribuirse en el paquete npm.
- *
- * Por qué existe:
- *   Tanto `scripts/limpiar-artefactos-python.js` (prepack) como
- *   `scripts/publicar.js` (copiarDir hacia tmpDir del mirror GH)
- *   necesitan saber qué directorios y extensiones excluir. Tener la
- *   lista hardcodeada en cada archivo es violación DRY de conocimiento
- *   — agregar `.pyd` o `.mypy_cache_v2` exigiría editar dos archivos
- *   y mantenerlos sincronizados.
- */
-
-const DIRS_ARTEFACTOS_PYTHON = Object.freeze(new Set([
-  '__pycache__',
-  '.pytest_cache',
-  '.mypy_cache',
-  '.ruff_cache',
-]));
-
-const EXTS_ARTEFACTOS_PYTHON = Object.freeze(new Set([
-  '.pyc',
-  '.pyo',
-]));
-
-function esDirArtefacto(nombre) {
-  return DIRS_ARTEFACTOS_PYTHON.has(nombre);
-}
-
-function esArchivoArtefacto(nombre) {
-  const dot = nombre.lastIndexOf('.');
-  if (dot < 0) return false;
-  return EXTS_ARTEFACTOS_PYTHON.has(nombre.slice(dot).toLowerCase());
-}
-
-module.exports = {
-  DIRS_ARTEFACTOS_PYTHON,
-  EXTS_ARTEFACTOS_PYTHON,
-  esDirArtefacto,
-  esArchivoArtefacto,
-};
+'use strict';
+
+/**
+ * artefactos-python.js — fuente única de verdad para los artefactos
+ * Python que NO deben distribuirse en el paquete npm.
+ *
+ * Por qué existe:
+ *   Tanto `scripts/limpiar-artefactos-python.js` (prepack) como
+ *   `scripts/publicar.js` (copiarDir hacia tmpDir del mirror GH)
+ *   necesitan saber qué directorios y extensiones excluir. Tener la
+ *   lista hardcodeada en cada archivo es violación DRY de conocimiento
+ *   — agregar `.pyd` o `.mypy_cache_v2` exigiría editar dos archivos
+ *   y mantenerlos sincronizados.
+ */
+
+const DIRS_ARTEFACTOS_PYTHON = Object.freeze(new Set([
+  '__pycache__',
+  '.pytest_cache',
+  '.mypy_cache',
+  '.ruff_cache',
+]));
+
+const EXTS_ARTEFACTOS_PYTHON = Object.freeze(new Set([
+  '.pyc',
+  '.pyo',
+]));
+
+function esDirArtefacto(nombre) {
+  return DIRS_ARTEFACTOS_PYTHON.has(nombre);
+}
+
+function esArchivoArtefacto(nombre) {
+  const dot = nombre.lastIndexOf('.');
+  if (dot < 0) return false;
+  return EXTS_ARTEFACTOS_PYTHON.has(nombre.slice(dot).toLowerCase());
+}
+
+module.exports = {
+  DIRS_ARTEFACTOS_PYTHON,
+  EXTS_ARTEFACTOS_PYTHON,
+  esDirArtefacto,
+  esArchivoArtefacto,
+};

package/scripts/lib/benchmark-metrics.js

@@ -1,160 +1,160 @@
-'use strict';
-
-/**
- * benchmark-metrics.js — Métricas de retrieval para benchmark de memoria SWL.
- *
- * Patrón adoptado de `temp/agentmemory-main/benchmark/longmemeval-bench.ts`.
- * Funciones puras zero-deps. Adaptado a IDs SWL (aprendizaje, sesion,
- * instinto) en lugar de session_id de agentmemory.
- *
- * Métricas:
- *   - recallAt(k): 1.0 si al menos un gold ID está en los top-k, sino 0.0
- *   - precisionAt(k): proporción de top-k que son gold
- *   - mrr: Mean Reciprocal Rank (1/rank del primer gold encontrado)
- *   - ndcgAt(k): Normalized Discounted Cumulative Gain
- *
- * @module scripts/lib/benchmark-metrics
- */
-
-// ── helpers ───────────────────────────────────────────────────────────────────
-
-function asSet(arr) {
-  return new Set(Array.isArray(arr) ? arr : []);
-}
-
-// ── métricas individuales ─────────────────────────────────────────────────────
-
-/**
- * Recall @ k: 1.0 si ALGÚN id gold está en los primeros k retrieved.
- *
- * @param {string[]} retrievedIds - IDs ordenados (mejor primero).
- * @param {string[]} goldIds - IDs correctos esperados.
- * @param {number} k
- * @returns {number} 0 o 1
- */
-function recallAt(retrievedIds, goldIds, k) {
-  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds)) return 0;
-  const topK = new Set(retrievedIds.slice(0, k));
-  return goldIds.some(g => topK.has(g)) ? 1.0 : 0.0;
-}
-
-/**
- * Precision @ k: proporción de los primeros k retrieved que son gold.
- *
- * @param {string[]} retrievedIds
- * @param {string[]} goldIds
- * @param {number} k
- * @returns {number} en [0, 1]
- */
-function precisionAt(retrievedIds, goldIds, k) {
-  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds) || k <= 0) return 0;
-  const goldSet = asSet(goldIds);
-  const topK = retrievedIds.slice(0, k);
-  if (topK.length === 0) return 0;
-  const hits = topK.filter(id => goldSet.has(id)).length;
-  return hits / topK.length;
-}
-
-/**
- * Mean Reciprocal Rank: 1/rank del primer gold encontrado, o 0 si ninguno.
- *
- * @param {string[]} retrievedIds
- * @param {string[]} goldIds
- * @returns {number} en [0, 1]
- */
-function mrr(retrievedIds, goldIds) {
-  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds)) return 0;
-  const goldSet = asSet(goldIds);
-  for (let i = 0; i < retrievedIds.length; i++) {
-    if (goldSet.has(retrievedIds[i])) {
-      return 1 / (i + 1);
-    }
-  }
-  return 0;
-}
-
-function dcg(relevancias, k) {
-  let suma = 0;
-  for (let i = 0; i < Math.min(k, relevancias.length); i++) {
-    suma += (relevancias[i] ? 1 : 0) / Math.log2(i + 2);
-  }
-  return suma;
-}
-
-/**
- * Normalized Discounted Cumulative Gain @ k.
- *
- * @param {string[]} retrievedIds
- * @param {string[]} goldIds
- * @param {number} k
- * @returns {number} en [0, 1]
- */
-function ndcgAt(retrievedIds, goldIds, k) {
-  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds) || k <= 0) return 0;
-  const goldSet = asSet(goldIds);
-  const rels = retrievedIds.slice(0, k).map(id => goldSet.has(id));
-  const idealRels = Array.from({ length: Math.min(k, goldSet.size) }, () => true);
-  const idealDCG = dcg(idealRels, k);
-  if (idealDCG === 0) return 0;
-  return dcg(rels, k) / idealDCG;
-}
-
-// ── agregados ─────────────────────────────────────────────────────────────────
-
-/**
- * Calcula el conjunto completo de métricas para una query.
- *
- * @param {string[]} retrievedIds
- * @param {string[]} goldIds
- * @returns {{ recall_at_5, recall_at_10, recall_at_20, mrr, ndcg_at_10, precision_at_5 }}
- */
-function calcularMetricas(retrievedIds, goldIds) {
-  return {
-    recall_at_5:    recallAt(retrievedIds, goldIds, 5),
-    recall_at_10:   recallAt(retrievedIds, goldIds, 10),
-    recall_at_20:   recallAt(retrievedIds, goldIds, 20),
-    mrr:            mrr(retrievedIds, goldIds),
-    ndcg_at_10:     ndcgAt(retrievedIds, goldIds, 10),
-    precision_at_5: precisionAt(retrievedIds, goldIds, 5),
-  };
-}
-
-/**
- * Promedia métricas sobre múltiples queries.
- *
- * @param {Array<object>} resultados - Array de objetos producidos por calcularMetricas().
- * @returns {object} Promedios con campo `n` (cantidad de queries).
- */
-function promediar(resultados) {
-  if (!Array.isArray(resultados) || resultados.length === 0) {
-    return {
-      n: 0,
-      recall_at_5: 0,
-      recall_at_10: 0,
-      recall_at_20: 0,
-      mrr: 0,
-      ndcg_at_10: 0,
-      precision_at_5: 0,
-    };
-  }
-
-  const claves = ['recall_at_5', 'recall_at_10', 'recall_at_20', 'mrr', 'ndcg_at_10', 'precision_at_5'];
-  const promedio = { n: resultados.length };
-  for (const k of claves) {
-    const sum = resultados.reduce((a, r) => a + (r[k] || 0), 0);
-    promedio[k] = sum / resultados.length;
-  }
-  return promedio;
-}
-
-// ── exports ───────────────────────────────────────────────────────────────────
-
-module.exports = {
-  recallAt,
-  precisionAt,
-  mrr,
-  ndcgAt,
-  dcg,
-  calcularMetricas,
-  promediar,
-};
+'use strict';
+
+/**
+ * benchmark-metrics.js — Métricas de retrieval para benchmark de memoria SWL.
+ *
+ * Patrón adoptado de `temp/agentmemory-main/benchmark/longmemeval-bench.ts`.
+ * Funciones puras zero-deps. Adaptado a IDs SWL (aprendizaje, sesion,
+ * instinto) en lugar de session_id de agentmemory.
+ *
+ * Métricas:
+ *   - recallAt(k): 1.0 si al menos un gold ID está en los top-k, sino 0.0
+ *   - precisionAt(k): proporción de top-k que son gold
+ *   - mrr: Mean Reciprocal Rank (1/rank del primer gold encontrado)
+ *   - ndcgAt(k): Normalized Discounted Cumulative Gain
+ *
+ * @module scripts/lib/benchmark-metrics
+ */
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function asSet(arr) {
+  return new Set(Array.isArray(arr) ? arr : []);
+}
+
+// ── métricas individuales ─────────────────────────────────────────────────────
+
+/**
+ * Recall @ k: 1.0 si ALGÚN id gold está en los primeros k retrieved.
+ *
+ * @param {string[]} retrievedIds - IDs ordenados (mejor primero).
+ * @param {string[]} goldIds - IDs correctos esperados.
+ * @param {number} k
+ * @returns {number} 0 o 1
+ */
+function recallAt(retrievedIds, goldIds, k) {
+  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds)) return 0;
+  const topK = new Set(retrievedIds.slice(0, k));
+  return goldIds.some(g => topK.has(g)) ? 1.0 : 0.0;
+}
+
+/**
+ * Precision @ k: proporción de los primeros k retrieved que son gold.
+ *
+ * @param {string[]} retrievedIds
+ * @param {string[]} goldIds
+ * @param {number} k
+ * @returns {number} en [0, 1]
+ */
+function precisionAt(retrievedIds, goldIds, k) {
+  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds) || k <= 0) return 0;
+  const goldSet = asSet(goldIds);
+  const topK = retrievedIds.slice(0, k);
+  if (topK.length === 0) return 0;
+  const hits = topK.filter(id => goldSet.has(id)).length;
+  return hits / topK.length;
+}
+
+/**
+ * Mean Reciprocal Rank: 1/rank del primer gold encontrado, o 0 si ninguno.
+ *
+ * @param {string[]} retrievedIds
+ * @param {string[]} goldIds
+ * @returns {number} en [0, 1]
+ */
+function mrr(retrievedIds, goldIds) {
+  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds)) return 0;
+  const goldSet = asSet(goldIds);
+  for (let i = 0; i < retrievedIds.length; i++) {
+    if (goldSet.has(retrievedIds[i])) {
+      return 1 / (i + 1);
+    }
+  }
+  return 0;
+}
+
+function dcg(relevancias, k) {
+  let suma = 0;
+  for (let i = 0; i < Math.min(k, relevancias.length); i++) {
+    suma += (relevancias[i] ? 1 : 0) / Math.log2(i + 2);
+  }
+  return suma;
+}
+
+/**
+ * Normalized Discounted Cumulative Gain @ k.
+ *
+ * @param {string[]} retrievedIds
+ * @param {string[]} goldIds
+ * @param {number} k
+ * @returns {number} en [0, 1]
+ */
+function ndcgAt(retrievedIds, goldIds, k) {
+  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds) || k <= 0) return 0;
+  const goldSet = asSet(goldIds);
+  const rels = retrievedIds.slice(0, k).map(id => goldSet.has(id));
+  const idealRels = Array.from({ length: Math.min(k, goldSet.size) }, () => true);
+  const idealDCG = dcg(idealRels, k);
+  if (idealDCG === 0) return 0;
+  return dcg(rels, k) / idealDCG;
+}
+
+// ── agregados ─────────────────────────────────────────────────────────────────
+
+/**
+ * Calcula el conjunto completo de métricas para una query.
+ *
+ * @param {string[]} retrievedIds
+ * @param {string[]} goldIds
+ * @returns {{ recall_at_5, recall_at_10, recall_at_20, mrr, ndcg_at_10, precision_at_5 }}
+ */
+function calcularMetricas(retrievedIds, goldIds) {
+  return {
+    recall_at_5:    recallAt(retrievedIds, goldIds, 5),
+    recall_at_10:   recallAt(retrievedIds, goldIds, 10),
+    recall_at_20:   recallAt(retrievedIds, goldIds, 20),
+    mrr:            mrr(retrievedIds, goldIds),
+    ndcg_at_10:     ndcgAt(retrievedIds, goldIds, 10),
+    precision_at_5: precisionAt(retrievedIds, goldIds, 5),
+  };
+}
+
+/**
+ * Promedia métricas sobre múltiples queries.
+ *
+ * @param {Array<object>} resultados - Array de objetos producidos por calcularMetricas().
+ * @returns {object} Promedios con campo `n` (cantidad de queries).
+ */
+function promediar(resultados) {
+  if (!Array.isArray(resultados) || resultados.length === 0) {
+    return {
+      n: 0,
+      recall_at_5: 0,
+      recall_at_10: 0,
+      recall_at_20: 0,
+      mrr: 0,
+      ndcg_at_10: 0,
+      precision_at_5: 0,
+    };
+  }
+
+  const claves = ['recall_at_5', 'recall_at_10', 'recall_at_20', 'mrr', 'ndcg_at_10', 'precision_at_5'];
+  const promedio = { n: resultados.length };
+  for (const k of claves) {
+    const sum = resultados.reduce((a, r) => a + (r[k] || 0), 0);
+    promedio[k] = sum / resultados.length;
+  }
+  return promedio;
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  recallAt,
+  precisionAt,
+  mrr,
+  ndcgAt,
+  dcg,
+  calcularMetricas,
+  promediar,
+};