@saulwade/swl-ses 2.6.1 → 2.8.0

package/scripts/lib/rrf-fusion.js

@@ -1,175 +1,175 @@
-'use strict';
-
-/**
- * rrf-fusion.js — Reciprocal Rank Fusion para combinar streams de búsqueda.
- *
- * Patrón adoptado de `temp/agentmemory-main/src/state/hybrid-search.ts`. El
- * algoritmo RRF combina rankings de múltiples sistemas de retrieval (BM25,
- * vector, graph) sin requerir que sus scores sean comparables — solo importa
- * la posición relativa (rank) en cada lista.
- *
- * Fórmula:
- *
- *     RRF(d) = Σ_i  w_i / (k + rank_i(d))
- *
- *   donde:
- *     d         = un documento candidato
- *     i         = índice del stream (BM25, vector, graph, ...)
- *     w_i       = peso del stream i (default 1.0 si no se especifica)
- *     rank_i(d) = posición 1-indexed de d en el stream i, o ∞ si no aparece
- *     k         = constante de smoothing (default 60, estándar Cormack 2009)
- *
- * Propiedades:
- *   - Robust frente a magnitudes de score heterogéneas — solo usa rank.
- *   - Documentos que aparecen en múltiples streams reciben boost natural.
- *   - Documentos que aparecen solo una vez no son penalizados — su rank ∞ en
- *     otros streams contribuye 0.
- *   - k ≈ 60 minimiza el peso de ranks bajos (< 60 efectivos).
- *
- * Versus suma simple de scores:
- *   - No requiere normalización entre streams (BM25 vs vector cosine son
- *     incomparables).
- *   - Más resistente a outliers (un score muy alto en un stream no domina).
- *
- * Sin dependencias — Node stdlib only. Backward compatible: el caller puede
- * mantener su lógica anterior y usar RRF solo cuando combine ≥2 streams.
- *
- * @module scripts/lib/rrf-fusion
- */
-
-// ── constantes ────────────────────────────────────────────────────────────────
-
-/** Constante k del RRF estándar (Cormack et al., 2009). */
-const RRF_K_DEFAULT = 60;
-
-// ── funciones puras ───────────────────────────────────────────────────────────
-
-/**
- * Construye un mapa `id → rank` desde un stream de resultados ordenados.
- * Rank es 1-indexed: el primer elemento tiene rank 1.
- * Si un id aparece varias veces, conserva el rank más bajo (mejor).
- *
- * @param {Array<{id: string}>} stream - Resultados ordenados (mejor primero).
- * @returns {Map<string, number>} Mapa id → rank.
- */
-function rankMap(stream) {
-  const map = new Map();
-  if (!Array.isArray(stream)) return map;
-  for (let i = 0; i < stream.length; i++) {
-    const item = stream[i];
-    if (!item || typeof item.id !== 'string') continue;
-    const rank = i + 1;
-    const previo = map.get(item.id);
-    if (previo === undefined || rank < previo) {
-      map.set(item.id, rank);
-    }
-  }
-  return map;
-}
-
-/**
- * Score parcial del stream para un id dado.
- * Si el id NO aparece en el stream, devuelve 0 (rank ∞).
- *
- * @param {Map<string, number>} map - Resultado de rankMap().
- * @param {string} id
- * @param {number} k
- * @returns {number} contribución 1/(k + rank), o 0 si no aparece.
- */
-function streamScore(map, id, k) {
-  const rank = map.get(id);
-  if (rank === undefined) return 0;
-  return 1 / (k + rank);
-}
-
-/**
- * Reciprocal Rank Fusion: combina N streams de búsqueda en un ranking unificado.
- *
- * Cada stream es un array de objetos con al menos `{ id: string }`. La posición
- * en el array determina el rank (1-indexed). Cualquier metadata extra (titulo,
- * fecha, score, etc.) del primer stream donde aparece el id se preserva en el
- * resultado.
- *
- * Si se proveen `weights`, se ponderan los streams. El array de pesos debe
- * tener el mismo largo que `streams`. Si no se provee, todos los streams pesan
- * 1.0. Pesos no positivos se tratan como 0 (efectivamente desactivan el stream).
- *
- * Si todos los pesos suman > 0, se normalizan a 1.0 para que el `combinedScore`
- * resultante sea comparable entre invocaciones con distintos pesos.
- *
- * @param {Array<Array<object>>} streams - Lista de streams ordenados.
- * @param {object} [opts]
- * @param {number} [opts.k=60] - Constante k del RRF.
- * @param {number[]} [opts.weights] - Pesos por stream (alineado con streams[]).
- * @param {number} [opts.limit] - Limita la salida a N elementos top.
- * @returns {Array<object>} Resultados combinados con `combinedScore`,
- *   ordenados descendente. Conserva metadata del primer stream donde apareció
- *   cada id.
- */
-function rrfFusion(streams, opts = {}) {
-  if (!Array.isArray(streams) || streams.length === 0) return [];
-
-  const k = typeof opts.k === 'number' && opts.k > 0 ? opts.k : RRF_K_DEFAULT;
-
-  // Normalizar pesos
-  let weights;
-  if (Array.isArray(opts.weights) && opts.weights.length === streams.length) {
-    const positivos = opts.weights.map(w =>
-      typeof w === 'number' && w > 0 ? w : 0,
-    );
-    const total = positivos.reduce((a, b) => a + b, 0);
-    weights = total > 0 ? positivos.map(w => w / total) : positivos;
-  } else {
-    // Sin weights explícitos: todos iguales y normalizados (suman 1.0).
-    const efectivos = streams.filter(s => Array.isArray(s) && s.length > 0).length;
-    if (efectivos === 0) return [];
-    weights = streams.map(s =>
-      Array.isArray(s) && s.length > 0 ? 1 / efectivos : 0,
-    );
-  }
-
-  // Construir rankMap por stream + recolectar metadata por id
-  const maps = streams.map(rankMap);
-  const metadata = new Map(); // id → primer item visto
-
-  for (const stream of streams) {
-    if (!Array.isArray(stream)) continue;
-    for (const item of stream) {
-      if (!item || typeof item.id !== 'string') continue;
-      if (!metadata.has(item.id)) {
-        metadata.set(item.id, item);
-      }
-    }
-  }
-
-  // Calcular combinedScore para cada id
-  const combined = [];
-  for (const id of metadata.keys()) {
-    let score = 0;
-    for (let i = 0; i < streams.length; i++) {
-      score += weights[i] * streamScore(maps[i], id, k);
-    }
-    if (score > 0) {
-      combined.push({
-        ...metadata.get(id),
-        combinedScore: score,
-      });
-    }
-  }
-
-  combined.sort((a, b) => b.combinedScore - a.combinedScore);
-
-  if (typeof opts.limit === 'number' && opts.limit > 0) {
-    return combined.slice(0, opts.limit);
-  }
-  return combined;
-}
-
-// ── exports ───────────────────────────────────────────────────────────────────
-
-module.exports = {
-  rrfFusion,
-  rankMap,
-  streamScore,
-  RRF_K_DEFAULT,
-};
+'use strict';
+
+/**
+ * rrf-fusion.js — Reciprocal Rank Fusion para combinar streams de búsqueda.
+ *
+ * Patrón adoptado de `temp/agentmemory-main/src/state/hybrid-search.ts`. El
+ * algoritmo RRF combina rankings de múltiples sistemas de retrieval (BM25,
+ * vector, graph) sin requerir que sus scores sean comparables — solo importa
+ * la posición relativa (rank) en cada lista.
+ *
+ * Fórmula:
+ *
+ *     RRF(d) = Σ_i  w_i / (k + rank_i(d))
+ *
+ *   donde:
+ *     d         = un documento candidato
+ *     i         = índice del stream (BM25, vector, graph, ...)
+ *     w_i       = peso del stream i (default 1.0 si no se especifica)
+ *     rank_i(d) = posición 1-indexed de d en el stream i, o ∞ si no aparece
+ *     k         = constante de smoothing (default 60, estándar Cormack 2009)
+ *
+ * Propiedades:
+ *   - Robust frente a magnitudes de score heterogéneas — solo usa rank.
+ *   - Documentos que aparecen en múltiples streams reciben boost natural.
+ *   - Documentos que aparecen solo una vez no son penalizados — su rank ∞ en
+ *     otros streams contribuye 0.
+ *   - k ≈ 60 minimiza el peso de ranks bajos (< 60 efectivos).
+ *
+ * Versus suma simple de scores:
+ *   - No requiere normalización entre streams (BM25 vs vector cosine son
+ *     incomparables).
+ *   - Más resistente a outliers (un score muy alto en un stream no domina).
+ *
+ * Sin dependencias — Node stdlib only. Backward compatible: el caller puede
+ * mantener su lógica anterior y usar RRF solo cuando combine ≥2 streams.
+ *
+ * @module scripts/lib/rrf-fusion
+ */
+
+// ── constantes ────────────────────────────────────────────────────────────────
+
+/** Constante k del RRF estándar (Cormack et al., 2009). */
+const RRF_K_DEFAULT = 60;
+
+// ── funciones puras ───────────────────────────────────────────────────────────
+
+/**
+ * Construye un mapa `id → rank` desde un stream de resultados ordenados.
+ * Rank es 1-indexed: el primer elemento tiene rank 1.
+ * Si un id aparece varias veces, conserva el rank más bajo (mejor).
+ *
+ * @param {Array<{id: string}>} stream - Resultados ordenados (mejor primero).
+ * @returns {Map<string, number>} Mapa id → rank.
+ */
+function rankMap(stream) {
+  const map = new Map();
+  if (!Array.isArray(stream)) return map;
+  for (let i = 0; i < stream.length; i++) {
+    const item = stream[i];
+    if (!item || typeof item.id !== 'string') continue;
+    const rank = i + 1;
+    const previo = map.get(item.id);
+    if (previo === undefined || rank < previo) {
+      map.set(item.id, rank);
+    }
+  }
+  return map;
+}
+
+/**
+ * Score parcial del stream para un id dado.
+ * Si el id NO aparece en el stream, devuelve 0 (rank ∞).
+ *
+ * @param {Map<string, number>} map - Resultado de rankMap().
+ * @param {string} id
+ * @param {number} k
+ * @returns {number} contribución 1/(k + rank), o 0 si no aparece.
+ */
+function streamScore(map, id, k) {
+  const rank = map.get(id);
+  if (rank === undefined) return 0;
+  return 1 / (k + rank);
+}
+
+/**
+ * Reciprocal Rank Fusion: combina N streams de búsqueda en un ranking unificado.
+ *
+ * Cada stream es un array de objetos con al menos `{ id: string }`. La posición
+ * en el array determina el rank (1-indexed). Cualquier metadata extra (titulo,
+ * fecha, score, etc.) del primer stream donde aparece el id se preserva en el
+ * resultado.
+ *
+ * Si se proveen `weights`, se ponderan los streams. El array de pesos debe
+ * tener el mismo largo que `streams`. Si no se provee, todos los streams pesan
+ * 1.0. Pesos no positivos se tratan como 0 (efectivamente desactivan el stream).
+ *
+ * Si todos los pesos suman > 0, se normalizan a 1.0 para que el `combinedScore`
+ * resultante sea comparable entre invocaciones con distintos pesos.
+ *
+ * @param {Array<Array<object>>} streams - Lista de streams ordenados.
+ * @param {object} [opts]
+ * @param {number} [opts.k=60] - Constante k del RRF.
+ * @param {number[]} [opts.weights] - Pesos por stream (alineado con streams[]).
+ * @param {number} [opts.limit] - Limita la salida a N elementos top.
+ * @returns {Array<object>} Resultados combinados con `combinedScore`,
+ *   ordenados descendente. Conserva metadata del primer stream donde apareció
+ *   cada id.
+ */
+function rrfFusion(streams, opts = {}) {
+  if (!Array.isArray(streams) || streams.length === 0) return [];
+
+  const k = typeof opts.k === 'number' && opts.k > 0 ? opts.k : RRF_K_DEFAULT;
+
+  // Normalizar pesos
+  let weights;
+  if (Array.isArray(opts.weights) && opts.weights.length === streams.length) {
+    const positivos = opts.weights.map(w =>
+      typeof w === 'number' && w > 0 ? w : 0,
+    );
+    const total = positivos.reduce((a, b) => a + b, 0);
+    weights = total > 0 ? positivos.map(w => w / total) : positivos;
+  } else {
+    // Sin weights explícitos: todos iguales y normalizados (suman 1.0).
+    const efectivos = streams.filter(s => Array.isArray(s) && s.length > 0).length;
+    if (efectivos === 0) return [];
+    weights = streams.map(s =>
+      Array.isArray(s) && s.length > 0 ? 1 / efectivos : 0,
+    );
+  }
+
+  // Construir rankMap por stream + recolectar metadata por id
+  const maps = streams.map(rankMap);
+  const metadata = new Map(); // id → primer item visto
+
+  for (const stream of streams) {
+    if (!Array.isArray(stream)) continue;
+    for (const item of stream) {
+      if (!item || typeof item.id !== 'string') continue;
+      if (!metadata.has(item.id)) {
+        metadata.set(item.id, item);
+      }
+    }
+  }
+
+  // Calcular combinedScore para cada id
+  const combined = [];
+  for (const id of metadata.keys()) {
+    let score = 0;
+    for (let i = 0; i < streams.length; i++) {
+      score += weights[i] * streamScore(maps[i], id, k);
+    }
+    if (score > 0) {
+      combined.push({
+        ...metadata.get(id),
+        combinedScore: score,
+      });
+    }
+  }
+
+  combined.sort((a, b) => b.combinedScore - a.combinedScore);
+
+  if (typeof opts.limit === 'number' && opts.limit > 0) {
+    return combined.slice(0, opts.limit);
+  }
+  return combined;
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  rrfFusion,
+  rankMap,
+  streamScore,
+  RRF_K_DEFAULT,
+};

package/scripts/lib/runtime-adapter-contract.js

@@ -0,0 +1,267 @@
+'use strict';
+
+/** Contrato cerrado de adaptadores Core-3 para C10/W3. */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const util = require('node:util');
+
+const { parsearJSONSeguro } = require('./frontmatter-canonico');
+
+const RAIZ = path.resolve(__dirname, '..', '..');
+const MANIFEST_DEFAULT = path.join(RAIZ, 'manifiestos', 'runtime-adapters-core3.json');
+const CORE_RUNTIME_IDS = Object.freeze(['claude-code', 'codex-cli', 'gemini-cli']);
+const INSTALLER_TARGETS = Object.freeze(['claude', 'codex', 'gemini']);
+const BINARY_CANDIDATES = Object.freeze([
+  Object.freeze(['claude', 'claude.exe']),
+  Object.freeze(['codex', 'codex.exe']),
+  Object.freeze(['gemini', 'gemini.cmd', 'gemini.exe']),
+]);
+const NATIVE_EVENTS = Object.freeze([['PreToolUse'], ['PreToolUse'], ['BeforeTool']]);
+const VERSION_PATTERNS = Object.freeze([
+  '^([0-9]+\\.[0-9]+\\.[0-9]+)(?:\\s.*)?$',
+  '^codex-cli\\s+([0-9]+\\.[0-9]+\\.[0-9]+)(?:\\s.*)?$',
+  '^([0-9]+\\.[0-9]+\\.[0-9]+)(?:\\s.*)?$',
+]);
+const SURFACE_IDS = Object.freeze([
+  'instructions', 'agents', 'skills', 'rules', 'commands', 'hooks',
+  'operationTranslation',
+]);
+const OUTPUT_IDS = Object.freeze(SURFACE_IDS.slice(0, -1));
+const CAPABILITY_STATES = Object.freeze(['native', 'emulated', 'unsupported', 'unverified']);
+const OUTPUT_FORMATS = Object.freeze({
+  instructions: Object.freeze(['markdown']),
+  agents: Object.freeze(['markdown-frontmatter', 'toml']),
+  skills: Object.freeze(['markdown-frontmatter']),
+  rules: Object.freeze(['markdown']),
+  commands: Object.freeze(['markdown-frontmatter', 'toml', 'none']),
+  hooks: Object.freeze(['json']),
+});
+const MAX_MANIFEST_BYTES = 256 * 1024;
+const MAX_STRING_BYTES = 2048;
+const MANIFEST_OPEN_FLAGS = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0);
+const ROOT_FIELDS = [
+  '$schemaVersion', 'kind', 'effectiveMode', 'coreSet', 'surfaces', 'runtimes',
+];
+const RUNTIME_FIELDS = [
+  'id', 'installerTarget', 'binaries', 'versionProbe', 'nativeEvents', 'outputFormats',
+  'capabilities', 'officialSources',
+];
+
+function esObjetoPlano(valor) {
+  if (valor === null || typeof valor !== 'object' || Array.isArray(valor)
+      || util.types.isProxy(valor)) return false;
+  const prototipo = Object.getPrototypeOf(valor);
+  return prototipo === Object.prototype || prototipo === null;
+}
+
+function esMaterialDatos(valor) {
+  if (Object.getOwnPropertySymbols(valor).length > 0) return false;
+  const descriptores = Object.values(Object.getOwnPropertyDescriptors(valor));
+  return descriptores.every((descriptor) => descriptor.enumerable && 'value' in descriptor);
+}
+
+function esArrayDatos(valor) {
+  if (util.types.isProxy(valor) || !Array.isArray(valor)
+      || Object.getOwnPropertySymbols(valor).length > 0) return false;
+  const descriptores = Object.getOwnPropertyDescriptors(valor);
+  const indices = Object.entries(descriptores).filter(([clave]) => clave !== 'length');
+  return indices.length === valor.length && indices.every(([clave, descriptor]) => (
+    /^(?:0|[1-9]\d*)$/u.test(clave) && descriptor.enumerable && 'value' in descriptor
+  ));
+}
+
+function assertShape(valor, campos, nombre) {
+  if (!esObjetoPlano(valor)) throw new TypeError(`${nombre} debe ser objeto plano`);
+  if (!esMaterialDatos(valor)) throw new TypeError(`${nombre}: material hostil`);
+  const faltante = campos.find((campo) => !Object.hasOwn(valor, campo));
+  if (faltante) throw new TypeError(`${nombre}: campo requerido ${faltante}`);
+  const extra = Object.keys(valor).find((campo) => !campos.includes(campo));
+  if (extra) throw new TypeError(`${nombre}: campo desconocido ${extra}`);
+}
+
+function assertArrayExacta(valor, esperado, nombre) {
+  if (!esArrayDatos(valor) || valor.length !== esperado.length
+      || valor.some((item, indice) => !Object.is(item, esperado[indice]))) {
+    throw new TypeError(`${nombre}: orden o contenido no corresponde al contrato`);
+  }
+}
+
+function validarRaiz(contrato) {
+  assertShape(contrato, ROOT_FIELDS, 'runtime adapter contract');
+  if (contrato.$schemaVersion !== '1.0.0') throw new TypeError('schema incompatible');
+  if (contrato.kind !== 'swl-runtime-adapters-core3') throw new TypeError('kind inválido');
+  if (contrato.effectiveMode !== 'proposal_only') {
+    throw new TypeError('effectiveMode debe ser proposal_only');
+  }
+  assertArrayExacta(contrato.coreSet, CORE_RUNTIME_IDS, 'Core-3');
+  assertArrayExacta(contrato.surfaces, SURFACE_IDS, 'surfaces');
+  if (!esArrayDatos(contrato.runtimes) || contrato.runtimes.length !== 3) {
+    throw new TypeError('runtimes debe contener exactamente Core-3');
+  }
+}
+
+function validarListaUnica(valor, nombre, patron) {
+  if (!esArrayDatos(valor) || valor.length === 0 || valor.length > 16
+      || new Set(valor).size !== valor.length) {
+    throw new TypeError(`${nombre} debe ser lista única no vacía`);
+  }
+  if (valor.some((item) => typeof item !== 'string' || item.length > 64 || !patron.test(item))) {
+    throw new TypeError(`${nombre} contiene valor inválido`);
+  }
+}
+
+function validarProbe(probe, indice) {
+  const campos = ['args', 'timeoutMs', 'maxOutputBytes', 'allowedExitCodes', 'parsePattern'];
+  assertShape(probe, campos, 'version probe');
+  assertArrayExacta(probe.args, ['--version'], 'version probe args');
+  assertArrayExacta(probe.allowedExitCodes, [0], 'version probe exit codes');
+  if (probe.timeoutMs !== 5000 || probe.maxOutputBytes !== 16384) {
+    throw new TypeError('version probe límites inválidos');
+  }
+  if (probe.parsePattern !== VERSION_PATTERNS[indice]) {
+    throw new TypeError('version probe parsePattern no es code-owned');
+  }
+}
+
+function esFechaIsoValida(valor) {
+  if (typeof valor !== 'string' || !/^\d{4}-\d{2}-\d{2}$/u.test(valor)) return false;
+  const fecha = new Date(`${valor}T00:00:00.000Z`);
+  if (Number.isNaN(fecha.valueOf())) return false;
+  const canonica = fecha.toISOString().slice(0, 10); // fecha-utc-ok: validación UTC deliberada
+  return canonica === valor;
+}
+
+function validarFuentes(fuentes) {
+  if (!esArrayDatos(fuentes) || fuentes.length === 0 || fuentes.length > 16) {
+    throw new TypeError('officialSources debe ser lista no vacía');
+  }
+  const urls = [];
+  for (const fuente of fuentes) {
+    assertShape(fuente, ['url', 'verifiedOn'], 'fuente oficial');
+    if (typeof fuente.url !== 'string' || fuente.url.length > MAX_STRING_BYTES
+        || !fuente.url.startsWith('https://')) {
+      throw new TypeError('fuente oficial debe usar HTTPS');
+    }
+    if (!esFechaIsoValida(fuente.verifiedOn)) {
+      throw new TypeError('fecha de fuente oficial inválida');
+    }
+    urls.push(fuente.url);
+  }
+  if (new Set(urls).size !== urls.length) throw new TypeError('fuente oficial duplicada');
+  return new Set(urls);
+}
+
+function validarOutputs(outputs) {
+  assertShape(outputs, OUTPUT_IDS, 'outputFormats');
+  for (const campo of OUTPUT_IDS) {
+    if (!OUTPUT_FORMATS[campo].includes(outputs[campo])) {
+      throw new TypeError(`output format inválido para ${campo}`);
+    }
+  }
+}
+
+function validarCapability(capability, fuentes, superficie) {
+  assertShape(capability, ['state', 'reason', 'source'], `capability ${superficie}`);
+  if (!CAPABILITY_STATES.includes(capability.state)) {
+    throw new TypeError(`estado inválido en capability ${superficie}`);
+  }
+  if (typeof capability.reason !== 'string' || capability.reason.length < 12
+      || capability.reason.length > 512) {
+    throw new TypeError(`razón inválida en capability ${superficie}`);
+  }
+  if (!fuentes.has(capability.source)) {
+    throw new TypeError(`fuente no declarada en capability ${superficie}`);
+  }
+}
+
+function validarCapabilities(capabilities, fuentes) {
+  assertShape(capabilities, SURFACE_IDS, 'capabilities');
+  for (const superficie of SURFACE_IDS) {
+    validarCapability(capabilities[superficie], fuentes, superficie);
+  }
+}
+
+function validarRuntime(runtime, indice) {
+  assertShape(runtime, RUNTIME_FIELDS, `runtime ${indice}`);
+  if (runtime.id !== CORE_RUNTIME_IDS[indice]) {
+    throw new TypeError('orden o ID de runtime inválido');
+  }
+  if (runtime.installerTarget !== INSTALLER_TARGETS[indice]) {
+    throw new TypeError('installerTarget de runtime inválido');
+  }
+  validarListaUnica(runtime.binaries, 'binarios', /^[A-Za-z0-9._-]+$/u);
+  assertArrayExacta(runtime.binaries, BINARY_CANDIDATES[indice], 'binarios code-owned');
+  validarProbe(runtime.versionProbe, indice);
+  assertArrayExacta(runtime.nativeEvents, NATIVE_EVENTS[indice], 'nativeEvents');
+  validarOutputs(runtime.outputFormats);
+  validarCapabilities(runtime.capabilities, validarFuentes(runtime.officialSources));
+}
+
+function validarContratoAdapters(contrato) {
+  validarRaiz(contrato);
+  contrato.runtimes.forEach(validarRuntime);
+  return contrato;
+}
+
+function identidadArchivo(stats) {
+  return [stats.dev, stats.ino, stats.size, stats.mtimeNs, stats.ctimeNs]
+    .map((valor) => String(valor)).join(':');
+}
+
+function validarStatsManifiesto(stats) {
+  if (!stats.isFile()) throw new TypeError('manifiesto debe ser archivo regular');
+  if (stats.size > BigInt(MAX_MANIFEST_BYTES)) {
+    throw new TypeError('manifiesto excede límite de bytes');
+  }
+}
+
+function leerBytesExactos(descriptor, longitud) {
+  const bytes = Buffer.alloc(longitud);
+  let offset = 0;
+  while (offset < longitud) {
+    const leidos = fs.readSync(descriptor, bytes, offset, longitud - offset, offset);
+    if (leidos === 0) throw new TypeError('manifiesto cambió durante lectura');
+    offset += leidos;
+  }
+  return bytes;
+}
+
+function leerManifiestoAcotado(manifestPath) {
+  const descriptor = fs.openSync(manifestPath, MANIFEST_OPEN_FLAGS);
+  try {
+    const antes = fs.fstatSync(descriptor, { bigint: true });
+    validarStatsManifiesto(antes);
+    const bytes = leerBytesExactos(descriptor, Number(antes.size));
+    const despues = fs.fstatSync(descriptor, { bigint: true });
+    validarStatsManifiesto(despues);
+    if (identidadArchivo(antes) !== identidadArchivo(despues)) {
+      throw new TypeError('manifiesto cambió durante lectura');
+    }
+    return bytes;
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+
+function congelarProfundo(valor) {
+  if (!valor || typeof valor !== 'object' || Object.isFrozen(valor)) return valor;
+  for (const hijo of Object.values(valor)) congelarProfundo(hijo);
+  return Object.freeze(valor);
+}
+
+function cargarContratoAdapters(opciones = {}) {
+  const manifestPath = opciones.manifestPath || MANIFEST_DEFAULT;
+  const bytes = leerManifiestoAcotado(manifestPath);
+  const { valor: contrato } = parsearJSONSeguro(bytes.toString('utf8'));
+  validarContratoAdapters(contrato);
+  return congelarProfundo(contrato);
+}
+
+module.exports = {
+  CAPABILITY_STATES,
+  CORE_RUNTIME_IDS,
+  SURFACE_IDS,
+  cargarContratoAdapters,
+  validarContratoAdapters,
+};