ESEKL — Capa de Conocimiento de Ingeniería de Software Empírica

ESEKL convierte la investigación de sistemas de código abierto de nivel de producción en un conjunto de herramientas estructuradas y utilizables por agentes. Se distribuye como un servidor del Model Context Protocol (MCP). Ese es el único mecanismo de entrega compatible.

Los agentes que trabajan con sistemas distribuidos — procesadores de colas, brokers, pipelines de streaming — alucinan habitualmente invariantes de comportamiento, citan incorrectamente los modos de fallo de producción y generan planes de verificación sin fundamento empírico. ESEKL elimina esa brecha. Proporciona conocimiento con trazabilidad de procedencia y etiquetas de evidencia, obtenido mediante inspección mecánica de sistemas de código abierto maduros, y expuesto a través de herramientas MCP orientadas a tareas que imponen una divulgación progresiva en lugar de un volcado de contexto en bruto.

El corpus actual cubre sistemas de colas, de brokers y de streaming: asynq, bullmq, pgmq, river, goqite, litequeue, nats-server, nsq, blazingmq, redpanda, rabbitmq, artemis y rocketmq.

Cómo ayuda a los agentes

Sin ESEKL, un agente de codificación o de planificación que trabaja con colas de trabajos debe o bien entrar en un edificio de invariantes de comportamiento, o bien examinar miles de líneas de código fuente en bruto para alucinar patrones. Ambas vías fallan: la invención produce invariantes incorrectos; el examen de archivos sin tratar satura la ventana de contexto antes de que el agente، no llega a la evidencia correspondiente.

ESEKL proporciona:

• Invariantes de comportamiento destilados de la inspección directa de la fuente en todo el corpus, cada uno etiquetado con la forma en que se ha obtenido (SOURCE_OBSERVED, TEST_OBSERVED, HISTORY_SUPPORTED).

• Cadenas de modos de fallo obtenidas a partir de errores reales de producción y de regresiones, trazables hasta el hash de commit exacto y la función de prueba que los resolvieron.

• Paquetes de implementación — consultas SQL concretas, scripts de Lua y fragmentos de Go/TypeScript extraídos de archivos de producción — servidos con filtros de sustrato y de mecanismo para que el agente reciba exactamente la clase de implementación hacia la que está trabajando.

• Críticas de diseño contrastadas contra los invariantes del corpus o de otro corpus, que sacan a la superficie garantías de fencing ausentes, riesgos de deriva de reloj y lagunas de aislamiento de trabajos tóxicos en la arquitectura propuesta por el agente.

• Planes de verificación adversariales generados a partir de evidencias de error empíricas, listos para alimentar la suite de pruebas.

Cada resultado lleva una etiqueta epistémica. Agents nunca confunden una abstracción que atraviesa varios repositorios con una inferencia de modelo.

Related MCP server: PactAI MCP

Arquitectura: cómo se construyen las EKUs

flowchart TD
    A["Tier 0: Raw Codebase\n(factory/<repo>)"]
    B["Tier 1: Atomic Observations\n(eku_middleware/eku_store/evidence/observations.json)\nExact file path, line range, verbatim snippet,\nlanguage, substrate"]
    C["Tier 2: Repo-Local EKUs\n(eku_middleware/eku_store/repo_ekus/<repo>.json)\nConcrete mechanism, source snippet,\ntest provenance, failure provenance\nEpistemic: REPO_LOCAL"]
    D["Tier 3: Domain EKUs\n(eku_middleware/eku_store/synthesized_queue_ekus.json)\nCross-repository behavioral invariants,\ndesign contracts, falsification audits\nEpistemic: DOMAIN_ABSTRACTION"]
    E["MCP Server\n(esekl mcp)\nProgressively discloses\nTier 1-3 via 20 tools"]
    F["Agent\n(Claude, Codex, AGY, etc.)"]

    A -->|"Mechanical inspection\nAST + grep + test suite link"| B
    B -->|"RepoEKU authoring\nvalidate_evidence_ledger.py"| C
    C -->|"Cross-corpus synthesis\nClaim matrix + keyword groups"| D
    D --> E
    C --> E
    B --> E
    E -->|"JSON-RPC 2.0 / stdio"| F

El directorio de fábrica contiene los checkouts de los repositorios de origen asignados a un commit. La inspección es mecánica: las rutas de los archivos, los rangos de líneas, los fragmentos de código textuales y los nombres de las funciones de prueba se capturan como Observaciones Atómicas. Estas observaciones se agrupan en EKUs de repositorio — registros concretos, basados en pruebas, ligados a un único repositorio — y se sintetizan en EKUs, más de dominio, en las que se formulan invariantes de comportamiento de carácter transversal con auditorías de falsación explícitas. El servidor MCP lee el almacén estático y lo expone a través de herramientas con divulgación progresiva. Los agentes interactúan solo a través de esas herramientas; nunca tocan el almacén en bruto.

El almacén de conocimiento (eku_store/) se distribuye empaquetado dentro del paquete npm. No se requiere ningún paso de inicialización. Añada la configuración MCP una sola vez y cualquier máquina que pueda ejectar npx tendrá el corpus completo de inmediato.

Instalación

No se requiere ningún paso de instalación.

El directorio eku_store/ está incluido directamente dentro del paquete npm esekl. Cuando se inicia npx esekl mcp, el servidor resuelve el almacén desde el directorio del paquete — sin copia local, sin init, sin configurar ningún proyecto.

Conecta el servidor MCP en tu host de agente utilizando unas de las siguientes configuraciones.

Configuración MCP

Este bloque JSON funciona en cualquier máquina, en cualquier project, sin rutas y sin preparación previa:

{
  "mcpServers": {
    "esekl": {
      "command": "npx",
      "args": ["-y", "esekl", "mcp"]
    }
  }
}

Orden de resolución del almacén (la primera coincidencia gana):

1. --store-root=<path> — anulación explícita, para uso avanzado.

2. ~/.esekl/store — si has ejecutado esekl init para tener un corpus totalmente offline o personalizado.

3. <package_dir>/eku_store — empacado en el paquete, siempre disponible, sin configuración.

Claude Desktop

Edita ~/.config/claude/claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json) y añade el bloque anterior. Reinicia Claude Desktop.

AGY (Antigravity)

Añade el bloque anterior al archivo de configuración MCP de AGY. En la mayoría de las configuraciones de AGY no hay que reiniciar.

Codex CLI

Añade a ~/.codex/config.toml:

[mcp_servers.esekl]
command = "npx"
args = ["-y", "esekl", "mcp"]

Para entornos Codex que acepten configuración JSON con mcpServers, usa el bloque JSON anterior.

Superficie de herramientas

El servidor MCP expone 20 herramientas en tres niveles de profundidad.

Descubrimiento y navegación (6 herramientas)

Evidencia y recuperación en capas (12 herramientas)

Crítica de diseño y verificación (2 herramientas)

Información sobre las herramientas:

• search_evidence — Búsqueda en la capa: "layer", en EKUs del dominio, afirmaciones, observaciones, fallos. Ahora con filtro layer.

• get_eku — Toda la EKU: invariante de comportamiento, contrato de diseño, contrato de verificación, estadísticas del corpus. Equival to get_eku.

• list_repo_ekus — Listado paginado de las EKUs de repositorio, con filtros por tipo de mecanismo/objeto.

• get_repo_eku — Regresa la EKU local con líneas en crudo del código, SQL/Lua snippet y procedencia del test suite.

• list_keyword_groups — Agrupación de keywords y sustratos cross-cuting, agregando EKUs de repositorio.

• get_keyword_group — Colección completa, incluyendo las RepoEKUs participantes y las Domain EKUs vinculadas.

• trace_domain_eku — Después traces Domain EKU to its originating Repo-EKUs, keyword groups, and raw observations.

• get_failure_patterns — Patrones de fallo y firmas de vulnerabilidad de segundo orden, para un problema.

• get_failure_chains — Cadenas causales de una caída: trigger, invariante rota, fallo terminal, estado del test de regresión.

• get_implementation_evidence — Packets de implementación, filtrados por sustrato y mecanismo.

• explain_provenance — Baja a la ruta de fichero exacta, rango, commit, SHA del snippet y test function.

• get_data_quality_report — Análisis de los Repo and Domain EKUs, para localizar campos faltantes y references rotas.

Crítica de diseño y verificación (2 herramientas)

Formatos de los resultados

get_eku

{
  "id": "EKU-QUEUE-015",
  "title": "Fenced Domain Result Promotion & Outbox Emission",
  "objectType": "BEHAVIORAL_INVARIANT",
  "claimId": "CLM-015",
  "problem": "A queue can fence stale completion of the job row while still allowing a superseded worker to write authoritative domain results or emit an outbox event.",
  "behavioralInvariant": "Ownership fencing must guard every authoritative side-effecting state mutation, including domain result promotion or outbox emission, not only queue-row completion.",
  "designContract": "Before committing a result row, payment ledger projection, or sendable outbox record, the storage transaction must prove current job ownership by token/generation.",
  "verificationContract": [
    "Worker A owns generation 1 and pauses.",
    "Worker B owns generation 2 and completes.",
    "Worker A attempts domain result promotion and queue completion.",
    "Both stale writes affect zero authoritative rows and emit stale-owner telemetry."
  ],
  "supportingEvidence": ["OBS-BULLMQ-002", "OBS-LITEQUEUE-002"],
  "historicalEvidence": ["HIST-RIVER-003"],
  "corpusStats": {
    "corpusSize": 13,
    "applicable": 7,
    "supports": 2,
    "counterexamples": 3
  }
}

get_repo_eku

{
  "repoEku": {
    "id": "REKU-RIVER-001",
    "repository": "river",
    "mechanism": "Relational Lock-Free Dequeue (FOR UPDATE SKIP LOCKED)",
    "claim": "PostgreSQL FOR UPDATE SKIP LOCKED allows concurrent worker pools to acquire non-overlapping available jobs without table-level locking.",
    "localContext": "River implements its primary job queue inside PostgreSQL. It relies on FOR UPDATE SKIP LOCKED in its sqlc query to scale Go worker goroutines.",
    "sourceProvenance": {
      "filePath": "riverdriver/riverpgxv5/internal/dbsqlc/river_job.sql",
      "lineRange": [45, 55],
      "queryOrCodeSnippet": "SELECT id, args, attempt, state FROM river_job WHERE state = 'available' ORDER BY priority ASC, scheduled_at ASC LIMIT $1 FOR UPDATE SKIP LOCKED;"
    },
    "testProvenance": {
      "filePath": "internal/jobexecutor/job_executor_test.go",
      "testName": "TestJobExecutor"
    },
    "epistemicStatus": "REPO_LOCAL"
  }
}

explain_provenance

{
  "evidenceId": "OBS-BULLMQ-002",
  "type": "OBSERVATION",
  "repository": "taskforcesh/bullmq",
  "commitHash": "c06b51cd3aacd0d9ee65e2544220c89f24d2479c",
  "filePath": "src/commands/moveToFinished-12.lua",
  "lineRange": { "start": 40, "end": 44 },
  "sourceUrl": "https://github.com/taskforcesh/bullmq/blob/c06b51cd3aacd0d9ee65e2544220c89f24d2479c/src/commands/moveToFinished-12.lua#L40-L44",
  "snippetSha256": "4b68e98da6984e1b00ad99e74d1c448bb5bbcb110cb16246473133604f32616f",
  "epistemicStatus": "SOURCE_OBSERVED"
}

compare_design_against_evidence

{
  "matchingEkus": ["EKU-QUEUE-015", "EKU-QUEUE-016", "EKU-QUEUE-017"],
  "missingInvariants": [
    {
      "invariant": "Storage-Time Lease Evaluation",
      "severity": "CRITICAL",
      "risk": "Caller-supplied VM timestamps allow clock drift across container hosts to cause premature lease expiration or duplicate execution.",
      "recommendedFix": "Use database server time (e.g. clock_timestamp()) exclusively in lease recovery queries."
    }
  ],
  "whatNotToPromise": [
    "Never promise true exactly-once delivery over external network boundaries without partner idempotency keys.",
    "Never promise constant latency during unmetered enterprise batch spikes; enforce admission semaphores and HTTP 429/503."
  ],
  "epistemicClassification": {
    "empiricalEvidenceCount": 8,
    "modelInferredPoints": 2
  }
}

Estructura del repositorio

eku_middleware/          npm package root (published as esekl)
  bin/                   CLI and MCP server entry points
  src/                   MCP server implementation
  eku_store/             Static knowledge store — ships bundled inside the package
    evidence/            Atomic observations and historical failure records
    repo_ekus/           Repo-Local EKUs per repository
    synthesized_queue_ekus.json   Cross-corpus Domain EKUs
    claim_matrix.json             Claim-to-corpus coverage matrix
    schema/              JSON schema and specification for RepoEKUs
    release/             factory_repo_lock.json — commit-pinned source provenance
  mcp_contract.md        Full JSON-RPC contract with input/output schemas

analyzer/                Validation scripts (not shipped in npm package)
factory/                 Local raw repository cache for research rounds (git-ignored)

Etiquetas epistémicas

Todos los resultados de las herramientas llevan etiquetas explícitas. Los agentes no deben eliminarlas ni ignorarlas.

Contrato MCP completo

Encuentra los esquemas de entrada y salida del total de las 20 herramientas en eku_middleware/mcp_contract.md