@saulwade/swl-ses 2.6.1 → 2.8.0

package/scripts/lib/harness-ir.js

@@ -0,0 +1,778 @@
+'use strict';
+
+/**
+ * Compilador diagnóstico del Harness IR sobre fuentes tracked y confinadas.
+ * La normalización semántica se incorpora en la siguiente oleada de la Fase 29.
+ */
+
+const SCHEMA = require('../../schemas/harness-ir.schema.json');
+const crypto = require('node:crypto');
+
+const { capturarHarnessSourceSnapshot } = require('./harness-source-snapshot');
+const { CENTINELA_TODOS, SKILLS_EXTERNAS_SET } = require('./skills-externas');
+
+const HOOKS_CONFIG = 'manifiestos/hooks-config.json';
+const TIPOS = Object.freeze(['agent', 'command', 'skill', 'rule']);
+const CAPABILITIES = Object.freeze([
+  'delegate',
+  'filesystem.mutate',
+  'filesystem.read',
+  'memory.read',
+  'memory.write',
+  'network.access',
+  'shell.exec',
+  'skill.invoke',
+]);
+const TOOL_MAP = Object.freeze({
+  Agent: 'delegate',
+  Bash: 'shell.exec',
+  Edit: 'filesystem.mutate',
+  Glob: 'filesystem.read',
+  Grep: 'filesystem.read',
+  MultiEdit: 'filesystem.mutate',
+  Read: 'filesystem.read',
+  Skill: 'skill.invoke',
+  Task: 'delegate',
+  WebFetch: 'network.access',
+  WebSearch: 'network.access',
+  Write: 'filesystem.mutate',
+});
+const EVENT_MAP = Object.freeze({
+  PostToolUse: 'after_tool',
+  PreToolUse: 'before_tool',
+  SessionStart: 'session_start',
+  Stop: 'stop',
+  SubagentStart: 'before_agent',
+  SubagentStop: 'after_agent',
+});
+const EVENTOS_FUERA_V1 = new Set(['Notification', 'PreCompact', 'UserPromptSubmit']);
+const RISK_MAP = Object.freeze({ ALTO: 'high', BAJO: 'low', MEDIO: 'medium' });
+const TIER_MAP = Object.freeze({
+  fable: 'frontier',
+  haiku: 'light',
+  opus: 'critical',
+  sonnet: 'standard',
+});
+const TIER_DEFINITIONS = Object.freeze([
+  {
+    id: 'critical',
+    requirements: [
+      { key: 'reasoning', value: 'strong' },
+      { key: 'structuredOutput', value: 'required' },
+      { key: 'errorTolerance', value: 'low' },
+    ],
+    unresolvedDisposition: 'stop',
+  },
+  {
+    id: 'frontier',
+    requirements: [
+      { key: 'reasoning', value: 'maximum_available' },
+      { key: 'toolUse', value: 'required' },
+      { key: 'context', value: 'wide' },
+    ],
+    unresolvedDisposition: 'stop',
+  },
+  {
+    id: 'light',
+    requirements: [
+      { key: 'latency', value: 'low' },
+      { key: 'cost', value: 'low' },
+      { key: 'outputSchema', value: 'simple' },
+    ],
+    unresolvedDisposition: 'unresolved_in_w1',
+  },
+  {
+    id: 'standard',
+    requirements: [
+      { key: 'toolUse', value: 'reliable' },
+      { key: 'costLatency', value: 'balanced' },
+    ],
+    unresolvedDisposition: 'unresolved_in_w1',
+  },
+]);
+const ALLOWLISTS = Object.freeze({
+  agent: new Set([
+    'color', 'description', 'dominio', 'evolvable', 'evolvable_scope', 'exclusiones',
+    'fase', 'fragmentos', 'hardGuardrails', 'healthMetrics', 'invariantes', 'maxTurnos',
+    'model', 'modeloAlterno', 'name', 'nivelRiesgo', 'permisosComandos',
+    'permisosEscritura', 'permisosRed', 'permissionMode', 'skillsInvocables',
+    'skillsRestringidos', 'steering', 'strategy', 'toolBudget', 'tools',
+    'ventanaContexto', 'version',
+  ]),
+  command: new Set([
+    'allowed-tools', 'allowed_tools', 'argument-hint', 'description', 'name', 'tipo',
+    'user-invocable', 'version',
+  ]),
+  rule: new Set(['paths']),
+  skill: new Set([
+    'atlas_techniques', 'attack_techniques', 'author', 'd3fend_techniques',
+    'dependencias', 'deprecated', 'deprecated-reason', 'deprecated-replacement',
+    'deprecated-since', 'description', 'domain', 'evolvable', 'evolvable_scope',
+    'evolved', 'exclusiones', 'fuente', 'herramientasPermitidas', 'license', 'name',
+    'nist_ai_rmf', 'nist_csf', 'nivelRiesgo', 'provenance', 'skillsInvocables',
+    'tags', 'toolsRequeridos', 'user-invocable', 'version', 'when_to_use',
+  ]),
+});
+const LOCATOR_ONLY = Object.freeze({
+  agent: new Set([...ALLOWLISTS.agent].filter((clave) => ![
+    'description', 'model', 'name', 'nivelRiesgo', 'skillsInvocables', 'tools',
+  ].includes(clave))),
+  command: new Set(['tipo', 'user-invocable', 'version']),
+  rule: new Set([]),
+  skill: new Set([...ALLOWLISTS.skill].filter((clave) => !['description', 'name'].includes(clave))),
+});
+const TAINT_TERMS_V1 = Object.freeze([
+  'anthropic', 'claude', 'claude-code', 'claude-api', 'openai', 'codex', 'gemini',
+  'google', 'cursor', 'copilot', 'github-copilot', 'opencode', 'openclaude',
+  'fable', 'opus', 'sonnet', 'haiku', 'read', 'write', 'edit', 'multiedit', 'bash',
+  'grep', 'glob', 'agent', 'task', 'skill', 'websearch', 'webfetch', 'sessionstart',
+  'pretooluse', 'posttooluse', 'subagentstart', 'subagentstop', 'stop',
+  'userpromptsubmit', 'precompact', 'notification',
+]);
+const CONFUSABLES_V1 = Object.freeze({
+  'Α': 'a', 'Β': 'b', 'Ε': 'e', 'Η': 'h', 'Ι': 'i', 'Κ': 'k', 'Μ': 'm', 'Ν': 'n',
+  'Ο': 'o', 'Ρ': 'p', 'Τ': 't', 'Χ': 'x', 'а': 'a', 'с': 'c', 'е': 'e', 'і': 'i',
+  'ι': 'i', 'о': 'o', 'ο': 'o', 'р': 'p', 'ρ': 'p', 'ѕ': 's', 'х': 'x', 'χ': 'x',
+  'у': 'y', 'υ': 'y',
+});
+
+function resolverRef(referencia) {
+  return referencia.slice(2).split('/').reduce((actual, token) => {
+    const clave = token.replaceAll('~1', '/').replaceAll('~0', '~');
+    return actual[clave];
+  }, SCHEMA);
+}
+
+function coincideTipo(tipo, valor) {
+  if (tipo === 'null') return valor === null;
+  if (tipo === 'array') return Array.isArray(valor);
+  if (tipo === 'object') {
+    return valor !== null && typeof valor === 'object' && !Array.isArray(valor);
+  }
+  if (tipo === 'integer') return Number.isInteger(valor);
+  return typeof valor === tipo;
+}
+
+function error(errores, ruta, codigo) {
+  errores.push({ path: ruta, code: codigo });
+}
+
+function validarObjeto(definicion, valor, ruta, errores) {
+  const propiedades = definicion.properties;
+  for (const requerida of definicion.required) {
+    if (!Object.hasOwn(valor, requerida)) error(errores, `${ruta}/${requerida}`, 'required');
+  }
+  for (const clave of Object.keys(valor)) {
+    if (!Object.hasOwn(propiedades, clave)) error(errores, `${ruta}/${clave}`, 'additional');
+  }
+  for (const [clave, hija] of Object.entries(propiedades)) {
+    if (Object.hasOwn(valor, clave)) validar(hija, valor[clave], `${ruta}/${clave}`, errores);
+  }
+}
+
+function validarLimites(definicion, valor, ruta, errores) {
+  if (definicion.minimum !== undefined && valor < definicion.minimum) {
+    error(errores, ruta, 'minimum');
+  }
+  if (definicion.maximum !== undefined && valor > definicion.maximum) {
+    error(errores, ruta, 'maximum');
+  }
+  if (definicion.maxItems !== undefined && valor.length > definicion.maxItems) {
+    error(errores, ruta, 'maxItems');
+  }
+  if (definicion.minItems !== undefined && valor.length < definicion.minItems) {
+    error(errores, ruta, 'minItems');
+  }
+}
+
+function validarRestricciones(definicion, valor, ruta, errores) {
+  if (definicion.const !== undefined && valor !== definicion.const) error(errores, ruta, 'const');
+  if (definicion.enum && !definicion.enum.includes(valor)) error(errores, ruta, 'enum');
+  if (definicion.pattern) {
+    if (!new RegExp(definicion.pattern, 'u').test(valor)) error(errores, ruta, 'pattern');
+  }
+  validarLimites(definicion, valor, ruta, errores);
+}
+
+function validarOneOf(opciones, valor, ruta, errores) {
+  const coincidencias = opciones.filter((opcion) => {
+    const locales = [];
+    validar(opcion, valor, ruta, locales);
+    return locales.length === 0;
+  });
+  if (coincidencias.length !== 1) error(errores, ruta, 'oneOf');
+}
+
+function validar(definicion, valor, ruta, errores) {
+  if (definicion.$ref) return validar(resolverRef(definicion.$ref), valor, ruta, errores);
+  if (definicion.oneOf) {
+    validarOneOf(definicion.oneOf, valor, ruta, errores);
+    return;
+  }
+  if (definicion.type && !coincideTipo(definicion.type, valor)) {
+    error(errores, ruta, 'type');
+    return;
+  }
+  validarRestricciones(definicion, valor, ruta, errores);
+  if (definicion.type === 'object') validarObjeto(definicion, valor, ruta, errores);
+  if (definicion.type === 'array') {
+    valor.forEach((item, indice) => validar(definicion.items, item, `${ruta}/${indice}`, errores));
+  }
+}
+
+function validarContrato(valor) {
+  const errors = [];
+  validar(SCHEMA, valor, '$', errors);
+  return { ok: errors.length === 0, errors };
+}
+
+function crearErrorHarness(codigo, mensaje, extras = {}) {
+  const excepcion = new Error(mensaje);
+  Object.assign(excepcion, { codigo, ...extras });
+  return excepcion;
+}
+
+function sha256(valor) {
+  return crypto.createHash('sha256').update(valor).digest('hex');
+}
+
+function clavesExactas(valor, requeridas, opcionales = []) {
+  if (!valor || typeof valor !== 'object' || Array.isArray(valor)) return false;
+  const permitidas = new Set([...requeridas, ...opcionales]);
+  return requeridas.every((clave) => Object.hasOwn(valor, clave))
+    && Object.keys(valor).every((clave) => permitidas.has(clave));
+}
+
+function validarObjetoTipos(valor, tipos) {
+  return Object.entries(tipos).every(([clave, tipo]) => {
+    if (tipo === 'array:string') {
+      return Array.isArray(valor[clave]) && valor[clave].every((item) => typeof item === 'string');
+    }
+    if (tipo === 'integer') return Number.isInteger(valor[clave]);
+    return typeof valor[clave] === tipo;
+  });
+}
+
+function validarRaizHooks(config) {
+  const claves = [
+    'descripcion',
+    'prioridad_hooks',
+    'opciones_avanzadas_hooks',
+    'riskThresholds',
+    'costBudget',
+    'circuitBreaker',
+    'hooks',
+  ];
+  return clavesExactas(config, claves)
+    && typeof config.descripcion === 'string'
+    && clavesExactas(config.prioridad_hooks, ['descripcion', 'orden', 'regla'])
+    && validarObjetoTipos(config.prioridad_hooks, {
+      descripcion: 'string',
+      orden: 'array:string',
+      regla: 'string',
+    });
+}
+
+function validarOpcionesHooks(config) {
+  const opciones = config.opciones_avanzadas_hooks;
+  const thresholds = config.riskThresholds;
+  const budget = config.costBudget;
+  const breaker = config.circuitBreaker;
+  return clavesExactas(opciones, ['descripcion', 'timeout', 'async', 'once'])
+    && validarObjetoTipos(opciones, {
+      descripcion: 'string', timeout: 'string', async: 'string', once: 'string',
+    })
+    && clavesExactas(thresholds, ['allow', 'review', 'confirm'])
+    && validarObjetoTipos(thresholds, { allow: 'number', review: 'number', confirm: 'number' })
+    && clavesExactas(budget, ['maxUsd', 'maxTokens', 'alertAt'])
+    && validarObjetoTipos(budget, { maxUsd: 'number', maxTokens: 'integer', alertAt: 'number' })
+    && clavesExactas(breaker, ['maxConsecutiveFailures', 'halfOpenCooldownMs', 'auditThreshold'])
+    && validarObjetoTipos(breaker, {
+      maxConsecutiveFailures: 'integer',
+      halfOpenCooldownMs: 'integer',
+      auditThreshold: 'integer',
+    });
+}
+
+function validarEntradaHook(entrada) {
+  const requeridas = ['event', 'matcher', 'description', 'blocking'];
+  const opcionales = ['async', 'optIn', 'maxConsecutiveFailures', 'degradeOnFailure'];
+  if (!clavesExactas(entrada, requeridas, opcionales)) return false;
+  if (!validarObjetoTipos(entrada, {
+    event: 'string', matcher: 'string', description: 'string', blocking: 'boolean',
+  })) return false;
+  const tiposOpcionales = {
+    async: 'boolean',
+    optIn: 'string',
+    maxConsecutiveFailures: 'integer',
+    degradeOnFailure: 'string',
+  };
+  return Object.entries(tiposOpcionales).every(([clave, tipo]) => (
+    entrada[clave] === undefined || validarObjetoTipos(entrada, { [clave]: tipo })
+  ));
+}
+
+function validarHooksParseados(parsed) {
+  const config = parsed.valor;
+  const hooksValidos = validarRaizHooks(config)
+    && validarOpcionesHooks(config)
+    && clavesExactas(config.hooks, [], Object.keys(config.hooks))
+    && Object.values(config.hooks).every(validarEntradaHook);
+  if (!hooksValidos) throw crearErrorHarness('HOOKS_CONFIG_INVALID', 'Shape de hooks inválido');
+  return { config, propiedades: parsed.propiedades };
+}
+
+function locatorArchivo(texto) {
+  return {
+    kind: 'line-range',
+    startLine: 1,
+    endLine: Math.max(1, texto.split('\n').length),
+  };
+}
+
+function fuenteNodo(snapshot, locator) {
+  return { path: snapshot.path, sha256: snapshot.sha256, locator };
+}
+
+function fuenteCampo(registro, clave) {
+  const metadata = registro.parsed.campos[clave];
+  if (!metadata) return registro.node.source;
+  return fuenteNodo(registro.snapshot, {
+    kind: 'frontmatter-key',
+    keyHash: sha256(metadata.claveFuente),
+    startLine: metadata.locator.startLine,
+    endLine: metadata.locator.endLine,
+  });
+}
+
+function fuenteCuerpo(registro) {
+  const { cuerpo } = registro.parsed;
+  if (!cuerpo) return registro.node.source;
+  const prefijo = registro.snapshot.texto.slice(0, -cuerpo.length);
+  return fuenteNodo(registro.snapshot, {
+    kind: 'line-range',
+    startLine: prefijo.split('\n').length,
+    endLine: Math.max(1, registro.snapshot.texto.split('\n').length),
+  });
+}
+
+function crearDiagnostico(code, severity, nodeId, source) {
+  return { code, severity, blocksConsumption: true, nodeId, source };
+}
+
+function diagnosticar(registro, code, severity, source = registro.node.source) {
+  registro.diagnostics.push(crearDiagnostico(code, severity, registro.node.nodeId, source));
+}
+
+function escaparRegex(texto) {
+  return texto.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+
+function limpiarTaint(texto) {
+  return String(texto)
+    .replace(/\x1B\[[0-?]*[ -/]*[@-~]/gu, '')
+    .replace(/[\u200B-\u200D\u2060\uFEFF]/gu, '')
+    .normalize('NFKC')
+    .replace(/[`*_~]/gu, '');
+}
+
+function contieneTermino(texto) {
+  return TAINT_TERMS_V1.some((term) => new RegExp(
+    `(?<![\\p{L}\\p{N}])${escaparRegex(term)}(?![\\p{L}\\p{N}])`,
+    'iu'
+  ).test(texto));
+}
+
+function crearSkeleton(texto) {
+  return [...texto].map((caracter) => CONFUSABLES_V1[caracter] || caracter).join('');
+}
+
+function detectarTaint(texto) {
+  const limpio = limpiarTaint(texto);
+  const directo = contieneTermino(limpio);
+  const porSkeleton = contieneTermino(crearSkeleton(limpio));
+  return { tainted: directo || porSkeleton, obfuscated: !directo && porSkeleton };
+}
+
+function clasificarLegacy(registro, payloads) {
+  const detecciones = payloads.map((payload) => ({ ...payload, ...detectarTaint(payload.text) }));
+  const detectada = detecciones.find((payload) => payload.tainted);
+  registro.node.legacyStatus = detectada ? 'tainted' : 'neutrality_unproven';
+  registro.node.providerTainted = Boolean(detectada);
+  diagnosticar(
+    registro,
+    detectada ? 'PROVIDER_TAINT_DETECTED' : 'LEGACY_NEUTRALITY_UNPROVEN',
+    'warning',
+    detectada ? detectada.source : payloads[0].source
+  );
+  const ofuscada = detecciones.find((payload) => payload.obfuscated);
+  if (ofuscada) diagnosticar(
+    registro,
+    'OBFUSCATED_NATIVE_REFERENCE',
+    'warning',
+    ofuscada.source
+  );
+}
+
+function payloadsArchivo(registro, claves) {
+  const payloads = claves
+    .filter((clave) => registro.parsed.valor?.[clave] !== undefined)
+    .map((clave) => ({ text: registro.parsed.valor[clave], source: fuenteCampo(registro, clave) }));
+  payloads.push({ text: registro.parsed.cuerpo, source: fuenteCuerpo(registro) });
+  return payloads;
+}
+
+function validarAllowlist(registro) {
+  const permitidas = ALLOWLISTS[registro.node.kind];
+  for (const clave of Object.keys(registro.parsed.valor)) {
+    if (!permitidas.has(clave)) diagnosticar(
+      registro,
+      'SOURCE_PROPERTY_UNKNOWN',
+      'error',
+      fuenteCampo(registro, clave)
+    );
+  }
+}
+
+function registrarPropiedadesLegacy(registro) {
+  const locatorOnly = LOCATOR_ONLY[registro.node.kind];
+  for (const clave of Object.keys(registro.parsed.valor)) {
+    if (locatorOnly.has(clave)) diagnosticar(
+      registro,
+      'LEGACY_PROPERTY_UNMAPPED',
+      'warning',
+      fuenteCampo(registro, clave)
+    );
+  }
+}
+
+function mapearTools(registro, aliases, source) {
+  if (!Array.isArray(aliases)) {
+    diagnosticar(registro, 'TOOL_MAPPING_UNKNOWN', 'error', source);
+    return null;
+  }
+  const capabilities = new Set();
+  let esValido = true;
+  for (const alias of aliases) {
+    const capability = TOOL_MAP[alias];
+    if (!capability) {
+      esValido = false;
+      diagnosticar(registro, 'TOOL_MAPPING_UNKNOWN', 'error', source);
+    }
+    else capabilities.add(capability);
+  }
+  registro.node.capabilities = [...capabilities].sort();
+  return esValido ? registro.node.capabilities : null;
+}
+
+function mapearAgente(registro) {
+  const valor = registro.parsed.valor;
+  mapearTools(registro, valor.tools, fuenteCampo(registro, 'tools'));
+  registro.node.tier = TIER_MAP[valor.model] || null;
+  if (!registro.node.tier) diagnosticar(
+    registro,
+    'MODEL_TIER_MAPPING_UNKNOWN',
+    'error',
+    fuenteCampo(registro, 'model')
+  );
+  registro.node.risk = RISK_MAP[valor.nivelRiesgo] || null;
+  if (!registro.node.risk) diagnosticar(
+    registro,
+    'RISK_MAPPING_UNKNOWN',
+    'error',
+    fuenteCampo(registro, 'nivelRiesgo')
+  );
+  if (valor.modeloAlterno !== undefined) diagnosticar(
+    registro,
+    'LEGACY_ALTERNATE_MODEL_DECLARED',
+    'warning',
+    fuenteCampo(registro, 'modeloAlterno')
+  );
+  clasificarLegacy(registro, payloadsArchivo(registro, ['name', 'description']));
+}
+
+function toolsComando(registro) {
+  const valor = registro.parsed.valor;
+  const snake = Object.hasOwn(valor, 'allowed_tools');
+  const kebab = Object.hasOwn(valor, 'allowed-tools');
+  if (snake && kebab) {
+    diagnosticar(registro, 'COMMAND_TOOL_FIELD_CONFLICT', 'error', registro.node.source);
+    return;
+  }
+  if (!snake && !kebab) {
+    diagnosticar(registro, 'COMMAND_TOOL_FIELD_MISSING', 'error', registro.node.source);
+    return;
+  }
+  const clave = snake ? 'allowed_tools' : 'allowed-tools';
+  mapearTools(registro, valor[clave], fuenteCampo(registro, clave));
+}
+
+function mapearComando(registro) {
+  toolsComando(registro);
+  diagnosticar(registro, 'COMMAND_SEMANTICS_UNSTRUCTURED', 'warning', fuenteCuerpo(registro));
+  clasificarLegacy(
+    registro,
+    payloadsArchivo(registro, ['name', 'description', 'argument-hint'])
+  );
+}
+
+function mapearRecurso(registro) {
+  const claves = registro.node.kind === 'skill' ? ['name', 'description'] : [];
+  clasificarLegacy(registro, payloadsArchivo(registro, claves));
+}
+
+function aplicarSemanticaArchivo(registro) {
+  validarAllowlist(registro);
+  registrarPropiedadesLegacy(registro);
+  if (registro.node.kind === 'agent') mapearAgente(registro);
+  else if (registro.node.kind === 'command') mapearComando(registro);
+  else mapearRecurso(registro);
+}
+
+function nodoBase(kind, nodeId, source) {
+  return {
+    nodeId,
+    kind,
+    consumable: false,
+    legacyStatus: 'neutrality_unproven',
+    providerTainted: false,
+    sourceDigest: sha256(JSON.stringify(source)),
+    source,
+    selector: null,
+    capabilities: [],
+    events: [],
+    tier: null,
+    risk: null,
+    references: [],
+    policyReferences: [],
+    gates: [],
+  };
+}
+
+function compilarArchivo(entry) {
+  const descriptor = entry;
+  const snapshot = entry.source;
+  const parsed = entry.parsed;
+  const nodeId = `${descriptor.kind}:${sha256(descriptor.path)}`;
+  const node = nodoBase(
+    descriptor.kind,
+    nodeId,
+    fuenteNodo(snapshot, locatorArchivo(snapshot.texto))
+  );
+  const registro = { node, snapshot, parsed, diagnostics: [] };
+  aplicarSemanticaArchivo(registro);
+  return registro;
+}
+
+function mapearMatcher(registro, matcher) {
+  if (matcher === '') {
+    registro.node.selector = { kind: 'all_tools' };
+    return;
+  }
+  if (!/^[A-Za-z]+(?:\|[A-Za-z]+)*$/u.test(matcher)) {
+    diagnosticar(registro, 'HOOK_MATCHER_UNKNOWN', 'error');
+    return;
+  }
+  const capabilities = mapearTools(registro, matcher.split('|'), registro.node.source);
+  if (!capabilities) {
+    registro.diagnostics = registro.diagnostics.filter(
+      ({ code }) => code !== 'TOOL_MAPPING_UNKNOWN'
+    );
+    diagnosticar(registro, 'HOOK_MATCHER_UNKNOWN', 'error');
+    return;
+  }
+  registro.node.selector = { kind: 'capabilities', anyOf: capabilities };
+}
+
+function mapearEvento(registro, event) {
+  if (EVENT_MAP[event]) registro.node.events = [EVENT_MAP[event]];
+  else if (EVENTOS_FUERA_V1.has(event)) diagnosticar(
+    registro,
+    'SOURCE_EVENT_OUTSIDE_IR_V1',
+    'warning'
+  );
+  else diagnosticar(registro, 'EVENT_MAPPING_UNKNOWN', 'error');
+}
+
+function mapearHook(registro, entrada, clave) {
+  mapearEvento(registro, entrada.event);
+  mapearMatcher(registro, entrada.matcher);
+  clasificarLegacy(registro, [
+    { text: clave, source: registro.node.source },
+    { text: entrada.description, source: registro.node.source },
+  ]);
+}
+
+function compilarHooks(captura) {
+  const snapshot = captura.source;
+  const { config, propiedades } = validarHooksParseados(captura.parsed);
+  return Object.keys(config.hooks).map((clave) => {
+    const pointer = `/hooks/${clave.replaceAll('~', '~0').replaceAll('/', '~1')}`;
+    const nodeId = `hook:${sha256(`${HOOKS_CONFIG}\0${pointer}`)}`;
+    const locator = propiedades[pointer].locator;
+    const node = nodoBase('hook', nodeId, fuenteNodo(snapshot, locator));
+    const registro = { node, snapshot, parsed: null, diagnostics: [] };
+    mapearHook(registro, config.hooks[clave], clave);
+    return registro;
+  });
+}
+
+function normalizarReferencia(valor) {
+  return String(valor).normalize('NFKC').toLowerCase();
+}
+
+function indiceSkills(registros) {
+  const porPath = new Map();
+  const basenames = new Map();
+  for (const registro of registros.filter(({ node }) => node.kind === 'skill')) {
+    porPath.set(registro.node.source.path, registro);
+    const basename = registro.node.source.path.split('/')[1];
+    const normalizado = normalizarReferencia(basename);
+    basenames.set(normalizado, (basenames.get(normalizado) || 0) + 1);
+  }
+  return { porPath, basenames };
+}
+
+function referenciaHash(registro, referencia, code) {
+  const source = fuenteCampo(registro, 'skillsInvocables');
+  registro.node.policyReferences.push({ refHash: sha256(referencia), source });
+  diagnosticar(registro, code, 'warning', source);
+}
+
+function resolverReferenciaLocal(registro, referencia, skills) {
+  const sourcePath = `habilidades/${referencia}/SKILL.md`;
+  const destino = skills.porPath.get(sourcePath);
+  if (!destino) return false;
+  const basename = normalizarReferencia(referencia);
+  const nombre = normalizarReferencia(destino.parsed.valor.name);
+  if (skills.basenames.get(basename) !== 1 || nombre !== basename) return false;
+  registro.node.references.push(destino.node.nodeId);
+  return true;
+}
+
+function resolverReferencias(registros) {
+  const skills = indiceSkills(registros);
+  for (const registro of registros.filter(({ node }) => node.kind === 'agent')) {
+    const referencias = registro.parsed.valor.skillsInvocables;
+    if (!Array.isArray(referencias)) {
+      diagnosticar(
+        registro,
+        'SKILL_REFERENCE_UNKNOWN',
+        'error',
+        fuenteCampo(registro, 'skillsInvocables')
+      );
+      continue;
+    }
+    for (const referencia of referencias) {
+      if (resolverReferenciaLocal(registro, referencia, skills)) continue;
+      if (SKILLS_EXTERNAS_SET.has(referencia)) {
+        referenciaHash(registro, referencia, 'EXTERNAL_SKILL_REFERENCE');
+      } else if (referencia === CENTINELA_TODOS) {
+        referenciaHash(registro, referencia, 'LEGACY_SKILL_WILDCARD');
+      } else diagnosticar(
+        registro,
+        'SKILL_REFERENCE_UNKNOWN',
+        'error',
+        fuenteCampo(registro, 'skillsInvocables')
+      );
+    }
+    registro.node.references.sort();
+    registro.node.policyReferences.sort((a, b) => a.refHash.localeCompare(b.refHash));
+  }
+}
+
+function ordenarValor(valor) {
+  if (Array.isArray(valor)) return valor.map(ordenarValor);
+  if (!valor || typeof valor !== 'object') return valor;
+  return Object.fromEntries(
+    Object.keys(valor).sort().map((clave) => [clave, ordenarValor(valor[clave])])
+  );
+}
+
+function serializarVista(vista) {
+  return `${JSON.stringify(ordenarValor(vista), null, 2)}\n`;
+}
+
+function contarNodos(nodos, diagnostics) {
+  const counts = Object.fromEntries(TIPOS.map((tipo) => [tipo, 0]));
+  counts.hook = 0;
+  for (const nodo of nodos) counts[nodo.kind] += 1;
+  return {
+    agents: counts.agent,
+    commands: counts.command,
+    skills: counts.skill,
+    rules: counts.rule,
+    hooks: counts.hook,
+    total: nodos.length,
+    errors: diagnostics.filter(({ severity }) => severity === 'error').length,
+    warnings: diagnostics.filter(({ severity }) => severity === 'warning').length,
+    consumable: 0,
+  };
+}
+
+function catalogar(nodos, propiedad, ids) {
+  return ids.map((id) => ({
+    id,
+    declaredBy: nodos
+      .filter((nodo) => nodo[propiedad].includes(id))
+      .map(({ nodeId }) => nodeId)
+      .sort(),
+  }));
+}
+
+function compararDiagnosticos(a, b) {
+  return [a.code, a.nodeId, a.source.path, JSON.stringify(a.source.locator)]
+    .join('\0')
+    .localeCompare([b.code, b.nodeId, b.source.path, JSON.stringify(b.source.locator)].join('\0'));
+}
+
+function construirIR(nodos) {
+  return {
+    kind: 'harness-ir',
+    schemaVersion: '1.0.0',
+    nodes: [...nodos].sort((a, b) => a.nodeId.localeCompare(b.nodeId)),
+    capabilities: catalogar(nodos, 'capabilities', CAPABILITIES),
+    events: catalogar(nodos, 'events', Object.values(EVENT_MAP).sort()),
+    tiers: TIER_DEFINITIONS,
+  };
+}
+
+function construirVista(registros) {
+  const nodos = registros.map(({ node }) => node);
+  const diagnostics = registros
+    .flatMap((registro) => registro.diagnostics)
+    .sort(compararDiagnosticos);
+  const counts = contarNodos(nodos, diagnostics);
+  const compilado = construirIR(nodos);
+  const ir = counts.errors > 0 ? null : compilado;
+  const vista = {
+    kind: 'diagnostic-view',
+    schemaVersion: '1.0.0',
+    shadowStatus: 'diagnostic_only',
+    ir,
+    counts,
+    diagnostics,
+    corpusDigest: sha256(serializarVista({ ir, diagnostics })),
+  };
+  const validacion = validarContrato(vista);
+  if (!validacion.ok) throw crearErrorHarness(
+    'HARNESS_CONTRACT_INVALID',
+    'La vista generada viola el contrato',
+    { errors: validacion.errors }
+  );
+  return vista;
+}
+
+function compilarHarnessIR() {
+  const snapshot = capturarHarnessSourceSnapshot();
+  const registros = snapshot.entries.map(compilarArchivo);
+  registros.push(...compilarHooks(snapshot.hooks));
+  resolverReferencias(registros);
+  return construirVista(registros);
+}
+
+module.exports = {
+  compilarHarnessIR,
+  serializarVista,
+  validarContrato,
+};