HUQAN
Capa de verificación y gobernanza local-primero para agentes de IA, afirmaciones, escrituras de memoria y acciones riesgosas, con evidencia, compuertas de políticas, procedencia y Recibos de Confianza.
Documentación
HUQAN
La confianza no es verdad. Verifica antes de confiar.
HUQAN es una capa de gobernanza y verificación de IA local-primero y de confianza parcial para afirmaciones, escrituras de memoria y acciones seleccionadas de agentes. Conecta el trabajo asistido por IA con evidencia, procedencia, alcance del espacio de trabajo, políticas, aprobación, verificación, compuertas de riesgo, registros de auditoría y Recibos de Confianza.
HUQAN no es un LLM, un motor de verdad universal ni una promesa de que las alucinaciones desaparecerán. Su propósito es más limitado y práctico: hacer que los flujos de trabajo de agentes de IA compatibles sean más observables, revisables y responsables antes de que una salida se convierta en una entrada de memoria, decisión o acción del mundo real.
Inicio rápido · ¿Qué es HUQAN? · Cómo funciona · Capacidades · Formas de ejecución · Preguntas frecuentes · Alcance actual
Repositorio canónico: https://github.com/ali-ulu/huqan
Un piloto limitado de Recibos de Confianza local — evidencia, revisión, aprobación y contexto de auditoría; no es una verdad universal ni una afirmación de preparación para producción.
¿Qué es HUQAN?
Los sistemas de IA pueden producir resultados útiles mientras dejan preguntas importantes sin responder:
- ¿Qué evidencia respalda la afirmación?
- ¿Qué procedencia y alcance del espacio de trabajo aplican?
- ¿Fue revisada una escritura de memoria o una acción riesgosa?
- ¿Qué verificaciones de política y riesgo se utilizaron?
- ¿Por qué se permitió, bloqueó o escaló el resultado?
- ¿Qué registro auditable queda después de la decisión?
HUQAN añade un límite de confianza acotado, determinista y auditable alrededor de estas preguntas en sus rutas locales probadas. No hace que el modelo subyacente sea veraz por sí mismo. En cambio, ayuda a un desarrollador u operador a inspeccionar la evidencia y el contexto de decisión antes de confiar en un resultado compatible.
Definición breve: HUQAN es infraestructura de gobernanza local-primero para evidencia, procedencia, políticas, aprobación, verificación y Recibos de Confianza alrededor del trabajo asistido por IA.
¿Por qué HUQAN?
La distinción central es entre un sistema de IA que genera una salida y una persona o sistema que confía en esa salida. HUQAN se centra en el límite entre esos dos eventos.
| Necesidad | Contribución acotada de HUQAN |
|---|---|
| Trazabilidad de evidencia | Evidencia respaldada por grafo, referencias de procedencia, contexto de alcance y enlaces de recibos |
| Verificaciones repetibles | Verificación determinista, verificaciones de contradicción y resultados de políticas en rutas probadas |
| Revisión de acciones de agentes | Revisión, aprobación, ejecución en seco y límites de bloqueo en rutas compatibles, con escalamiento disponible donde se configura un límite de aprobación |
| Memoria protegida | Verificaciones de admisión y espacio de trabajo antes de escrituras de memoria canónicas |
| Auditabilidad | Contexto de auditoría orientado a apéndices, Recibos de Confianza canónicos y cadenas de recibos |
| Operación local-primero | CLI, servidor REST local, MCP, biblioteca y superficies de UI local sin un modelo alojado requerido |
Cómo funciona
claim, memory write, or agent action
↓
evidence + provenance + workspace scope
↓
verification + contradiction + risk checks
↓
policy decision and approval boundary
↓
ALLOW / REVIEW / QUARANTINE / DRY-RUN ONLY / BLOCK / REJECT
↓
Trust Receipt + audit context
No todos los resultados están disponibles en todas las rutas. La compuerta que protege las llamadas a herramientas responde allow, review, dry_run_only o block; la compuerta de admisión de memoria añade quarantine y reject, porque una escritura puede mantenerse aparte para inspección en lugar de rechazarse directamente.
El escalamiento es una decisión que toma una persona, no una que devuelve la compuerta. Donde se configura un límite de aprobación, un revisor puede escalar un caso pendiente en lugar de decidirlo: el caso pasa a escalated y nada se ejecuta hasta que la autoridad a la que se elevó decida. Eso es un control multiparte, por lo que merece su lugar en una organización con más de un aprobador y simplemente está ausente en una instalación de un solo usuario — no hay una segunda autoridad a la que elevar un caso. Los tipos de decisión son approve, reject, expire, cancel, escalate y override; consulte lib/human-oversight-approval-runtime.js.
El flujo principal de ejecución local es:
flowchart LR
A[Agent or user output] --> B[Evidence and provenance]
B --> C[Verification and contradiction checks]
C --> D[Scope, policy, and risk gates]
D -->|approved| E[Trusted state or permitted action]
D -->|blocked or uncertain| F[Block, review, quarantine, or dry-run]
F -->|approval boundary configured| H[Human decision: approve, reject, or escalate]
H -->|approved| E
E --> G[Trust Receipt]
F --> G
H --> G
Un resultado de verificación exitoso no es un certificado universal de verdad. Es un resultado producido dentro del límite configurado de evidencia, procedencia, espacio de trabajo, política y tiempo de ejecución.
Inicio rápido
Requisitos
Necesita Git, npm y Node.js 22.13.0 o más reciente. Se recomienda Node.js 22 LTS o 24 LTS. Puede ser necesario un conjunto de herramientas de compilación en plataformas que no puedan usar un binario better-sqlite3 precompilado.
Instalar el paquete publicado
npm install -g huqan
Esto instala dos comandos:
huqan— el CLI local.huqan-mcp— el servidor MCP sobre stdio.
Ninguno de los dos comandos requiere un archivo de configuración o clave API solo para iniciar.
Para una ejecución única sin instalación global:
npx -y huqan quickstart
Ejecutar desde el código fuente
git clone https://github.com/ali-ulu/huqan.git
cd huqan
npm ci
node cli.js quickstart
gh repo clone ali-ulu/huqan se puede usar en lugar de git clone.
Su primer Recibo de Confianza
huqan quickstart
Desde un checkout del código fuente, use npm ci && node cli.js quickstart. El inicio rápido ejercita el pipeline local: proponga una mutación huqan.learn, reciba una decisión de revisión, persista la aprobación, realice la escritura canónica, verifique la afirmación contra el grafo e imprima el Recibo de Confianza resultante.
La salida típica tiene esta forma:
HUQAN quickstart — learn -> review -> approve -> verify -> Trust Receipt
1. OK propose: huqan.learn -> review (mutating_requires_review), approval approval-…
2. OK approve: huqan.approve -> approved (actor cli-quickstart)
3. OK verify: verified (confidence 0.90)
4. OK receipt: receiptId … (status canonical)
El inicio rápido usa un almacén desechable en el directorio temporal. No escribe en su propia memoria y no relaja ninguna compuerta.
Ejecutar el piloto limitado de Recibos de Confianza
El repositorio también contiene un piloto limitado de Recibos de Confianza local:
npm run pilot:trust-receipt
Trátelo como un piloto acotado y una superficie de prueba, no como evidencia de un ecosistema completo de confianza compartida o preparación universal para producción.
Instalación más pequeña opcional
La ingesta de PDF (pdfjs-dist) y la exportación de recibos PDF (pdfkit) son dependencias opcionales. Para omitirlas:
npm install -g huqan --omit=optional
Leer un PDF o exportar un recibo como PDF requiere entonces el paquete correspondiente. La exportación de recibos JSON y otros adaptadores siguen siendo rutas separadas.
Capacidades actuales
El repositorio actual expone los siguientes primitivos y superficies de desarrollador. Cada capacidad permanece acotada por su adaptador, política, espacio de trabajo, aprobación y ruta de tiempo de ejecución específicos.
| Capacidad | Qué está documentado o ejercitado |
|---|---|
| Verificación respaldada por grafo | Las afirmaciones y relaciones se pueden verificar contra el grafo local en rutas compatibles |
| Evidencia y procedencia | Los flujos de verificación y recibos preservan el contexto de fuente y decisión donde la ruta lo proporciona |
| Verificaciones de contradicción | Las rutas de verificación compatibles pueden mostrar evidencia conflictiva en lugar de tratar silenciosamente cada afirmación como aceptada |
| Relaciones explícitas | El límite actual de lenguaje natural incluye marcadores CAUSES, PREVENTS, ENABLES y DEPENDS_ON |
| Admisión de memoria | Las escrituras de memoria canónicas pasan por verificaciones de admisión y espacio de trabajo |
| Compuertas de política y riesgo | Las acciones compatibles pueden producir resultados allow, block, review, escalate o dry_run_only |
| Aprobación humana | Las mutaciones protegidas pueden requerir un paso de aprobación separado antes de la escritura o acción canónica |
| Recibos de Confianza | Los registros de recibos canónicos preservan evidencia acotada, procedencia, decisión y contexto de auditoría |
| Prevención de errores | La raíz del paquete expone un núcleo de preflight determinista y de fallo verificado |
| Primitivos de paquete | Existen primitivos de paquete .huqan con compatibilidad de lector .axiom.json heredado donde está documentado |
| Superficies de desarrollador | CLI, REST, MCP, biblioteca, UI local y superficies de Visor de Recibos de Confianza de solo lectura están presentes |
| Transporte A2A | Cuatro rutas se envían pero están restringidas por despliegue y sin configurar por defecto |
| Firewall de acciones de agente | Rutas propiedad de HUQAN más el contrato de pre-ejecución huqan-gate independiente del agente; la aplicación externa existe solo donde un hook o envoltorio de cliente está realmente conectado |
Formas de ejecución
Como biblioteca
const Kernel = require('huqan'); // KernelV2, the canonical runtime
const kernel = new Kernel();
require('huqan') resuelve a KernelV2, el tiempo de ejecución utilizado por el CLI, el servidor REST y el servidor MCP. La superficie de compatibilidad más antigua KernelV1 sigue siendo accesible como require('huqan').KernelV1, pero está obsoleta y no es la opción de tiempo de ejecución canónica.
La raíz del paquete también expone el núcleo de Prevención de Errores:
const { createErrorPrevention } = require('huqan');
const prevention = createErrorPrevention(kernel.memory, {
verifyEvidence,
resolveApproval,
});
Esta es una superficie de paquete/biblioteca para memoria de fallos verificados, ciclo de vida de reglas gobernadas y decisiones de preflight deterministas. No es una herramienta MCP adicional.
CLI local
npm start
La invocación directa sigue disponible:
node cli.js
HUQAN actualmente maneja marcadores de relación explícitos compatibles. No es un motor de comprensión de lenguaje natural de propósito general.
Servidor REST local
Los endpoints de mutación requieren una clave API:
HUQAN_API_KEY=replace-with-a-secret npm run server
El servidor se inicia en http://localhost:3000.
Los endpoints útiles incluyen:
| Endpoint | Método | Propósito |
|---|---|---|
/health | GET | Verificación de salud |
/api?q=... | GET | Superficie de consulta de solo lectura en lista permitida |
/graph-data | GET | Exportación del grafo de conocimiento |
/verify | POST | Verificación protegida |
/v2/verify | POST | Verificación estructurada protegida |
/upload | POST | Carga de alias protegida |
Las solicitudes de mutación autenticadas usan X-API-Key o Authorization: Bearer <key>. Revise el contrato de ruta y la política de autorización del espacio de trabajo antes de exponer un servidor local más allá de su límite previsto.
Servidor MCP para Claude o Cursor
huqan-mcp
Configuración de Claude Desktop sin instalación global previa:
{
"mcpServers": {
"huqan": {
"command": "npx",
"args": ["-y", "--package=huqan", "huqan-mcp"]
}
}
}
--package=huqan es necesario porque el nombre del binario difiere del nombre del paquete. Desde un checkout del código fuente, use "command": "node" con "args": ["/absolute/path/to/huqan/mcpServer.js"].
El catálogo MCP visible para el modelo incluye herramientas para aprendizaje, preguntas fundamentadas, verificación, planificación, ejecución de agentes acotada, vista previa/estado de ingesta, inspección de políticas, trazas de razonamiento, comparación, generación de hipótesis, defensa, búsqueda acotada, lectura de Recibos de Confianza y síntesis de conocimiento recursiva (huqan.fractal-learn, opcionalmente autoajustable a través de su modo autoTune unidireccional — puede ajustar sus propios umbrales pero nunca aflojarlos).
huqan.self-evolve ejecuta ese mismo bucle de síntesis y luego un pase de auto-evolución medido, e informa cuál de los dos se movió: su veredicto distingue una ejecución que solo cambió el contenido del grafo (native-content-only) de una que también cambió los umbrales que lo producen (native-writes-config), con inactive cuando nada se movió. Está clasificado como una escritura mutante y se mantiene para revisión humana exactamente como huqan.fractal-learn, por lo que el alcance que añade está en lo que una ejecución aprobada puede cambiar, no en lo que puede eludir.
Las herramientas solo para operadores se retienen deliberadamente de tools/list y requieren HUQAN_MCP_OPERATOR_TOKEN:
| Herramienta | Propósito |
|---|---|
huqan.approve | Aprobar o rechazar una aprobación pendiente |
huqan.approvals | Listar aprobaciones pendientes |
huqan.agent_resume | Reanudar una ejecución de agente suspendida |
Esta separación significa que un modelo que propone una acción mutante no puede aprobarla a través del catálogo visible para el modelo.
Las capacidades de operador son de un solo uso, y el registro de una gastada es duradero (#1674). Los nonces consumidos se escriben en .huqan-capability-nonces junto al almacén de memoria, por lo que una capacidad que ya se usó permanece usada a través de un reinicio y entre trabajadores; configure HUQAN_MCP_CAPABILITY_NONCE_DIR para apuntar a cada trabajador a un directorio compartido escribible cuando el predeterminado no esté en almacenamiento compartido. Si ese directorio no se puede escribir, la verificación de capacidad falla de forma cerrada en lugar de recurrir a protección de reproducción solo en memoria.
UI local y Visor de Recibos de Confianza
Inicie el servidor local para servir la UI de desarrollador conectada al backend:
npm run server
La UI local canónica es public/index.html. El Visor de Recibos de Confianza de solo lectura está disponible en /viewer en un servidor en ejecución y muestra los recibos que ya posee ese servidor local. No es una superficie de mutación ni una demostración de marketing estática pública.
Para un recorrido de observabilidad que cubre telemetría del servidor local, uso de herramientas, alertas, estado de la cola y pasos del panel, consulte Inicio rápido de observabilidad. Para la integración del ciclo de vida del framework a través del cliente de telemetría local estable, consulte Cliente de telemetría de observabilidad.
Acelerador de grafo Rust opcional
El repositorio contiene un acelerador JSON-IPC de Rust huqan-core opcional. No es necesario para la ruta normal de CLI, servidor, MCP o kernel.learn() canónica. Cuando el binario no está disponible, la ruta de JavaScript sigue siendo el comportamiento de referencia.
cd huqan-core
cargo build --release
cd ..
Para seleccionar un binario en otro lugar, establezca HUQAN_RUST_BIN antes de iniciar Node. Compare la ruta opcional con:
node benchmarks/rust-vs-js-graph.js 2000
El benchmark no afirma el rendimiento de Rust cuando no hay ningún binario presente.
Alcance actual
HUQAN es actualmente una capa de gobernanza de confianza parcial local-first. El proyecto es más sólido donde puede observar un flujo compatible, adjuntar evidencia y procedencia, evaluar puertas configuradas, requerir aprobación cuando corresponda y crear un registro de auditoría o Recibo de Confianza acotado.
Enviado y acotado
El repositorio contiene primitivas de verificación local, grafo, procedencia, aprobación, auditoría, recibo, memoria, puerta de acción, CLI, REST, MCP, UI y paquetes. También contiene dos suites de conformidad ejecutadas en el repositorio:
npm run conformance:external
npm run conformance:a2a
Estas suites son evidencia para los casos probados y las implementaciones que cubren. No son certificación de terceros ni prueba de interoperabilidad universal.
El paquete también incluye huqan-gate, un guardián de pre-ejecución independiente de la marca del agente. Su envoltorio genérico permite que un agente futuro reutilice la misma política sin agregar el nombre de ese agente al núcleo. Se incluyen proyecciones de Claude Code, Codex, OpenCode, Pi y Hermes. Esto es solo aplicación cuando el cliente realmente llama al guardián antes de la ejecución; los clientes sin enganche requieren un envoltorio, puerta de enlace o sandbox. Consulte Guardián de acción externa.
Las rutas A2A están limitadas por despliegue
Cuatro rutas se montan a través de lib/a2a/routes.js:
POST /api/a2a/exchangeGET /.well-known/agent-card.jsonPOST /api/a2a/negotiateGET /api/a2a/tasks/{taskId}
Con HUQAN_A2A_AUTHORITY_FILE y HUQAN_A2A_REPLAY_DIR sin establecer, las rutas responden 404 en lugar de 401; por lo tanto, una instalación no configurada no anuncia una superficie que no puede servir. La ruta de intercambio tiene condiciones adicionales de paquete/tiempo de ejecución documentadas en Despliegue A2A.
Implementado pero no alcanzable en producción
Algunos módulos están implementados y probados unitariamente, pero no son alcanzados por el grafo de puntos de entrada de producción declarado en lib/module-reachability.js. Una prueba unitaria que pasa para tal módulo prueba solo el comportamiento aislado; no prueba que el producto instalado ejecute ese módulo.
El informe de alcanzabilidad actual incluye entradas acotadas de V5, Self-Healer y conectores. Consulte el informe en vivo y Hoja de ruta operativa actual antes de describir cualquiera de ellos como generalmente disponible.
Lo que HUQAN no afirma
HUQAN no afirma:
- verdad universal o eliminación de alucinaciones de IA;
- aplicación en línea completa para cada conector, agente o ruta de mutación;
- un ecosistema de confianza compartida V5 terminado;
- interoperabilidad externa de terceros para el transporte A2A;
- un mercado público de agentes, red de certificación, insignia pública o economía de reputación;
- rendimiento de grafo a escala de Wikipedia;
- un Self-Healer autónomo completo;
- que un documento de diseño, hoja de ruta o prueba unitaria aislada sea equivalente a evidencia de despliegue en producción;
- que HUQAN reemplace IAM, seguridad de aplicaciones, seguridad de infraestructura, protección de datos o gobernanza humana.
Preguntas frecuentes
¿Es HUQAN un modelo de IA?
No. HUQAN es una capa de gobernanza y verificación local-first alrededor de flujos de trabajo asistidos por IA compatibles. No reemplaza el modelo de lenguaje que generó una salida.
¿HUQAN elimina las alucinaciones?
No. HUQAN no promete eliminar las alucinaciones. Ayuda a un flujo de trabajo compatible a inspeccionar evidencia y procedencia, aplicar políticas y límites de aprobación configurados, y registrar el contexto de decisión resultante.
¿Qué es un Recibo de Confianza?
Un Recibo de Confianza es un registro acotado y auditable de un flujo de verificación o gobernanza de acciones compatible. Puede preservar evidencia, procedencia, alcance, riesgo, revisión, aprobación y la decisión resultante. No es un certificado universal de que una afirmación sea verdadera.
¿Puede HUQAN bloquear una acción de agente?
En rutas de ejecución compatibles y conectadas, HUQAN puede producir decisiones como allow, review, dry_run_only o block. Los agentes externos pueden usar el envoltorio común huqan-gate y los adaptadores actuales, pero el enganche o envoltorio debe instalarse antes de la ejecución. La cobertura debe verificarse para el cliente, conector, ruta de mutación, identidad, política y configuración de despliegue particulares. HUQAN no afirma que un agente no conectado o sin enganche esté aplicado.
¿HUQAN reemplaza la seguridad empresarial?
No. HUQAN complementa la gestión de identidad y acceso, la seguridad de aplicaciones, la seguridad de infraestructura, la protección de datos y la supervisión humana. No reemplaza esos controles.
¿Puede HUQAN ejecutarse localmente sin un modelo alojado?
El grafo local central, la verificación, las puertas y las rutas de recibo no requieren un modelo alojado ni un servicio en la nube. Los adaptadores opcionales, integraciones y superficies limitadas por despliegue pueden tener sus propios requisitos.
¿Qué significa "confianza parcial"?
Significa que un resultado se evalúa dentro de límites explícitos de evidencia, procedencia, espacio de trabajo, política, aprobación y tiempo de ejecución. HUQAN no trata cada salida de modelo, entrada de memoria, conector o acción externa como automáticamente confiable.
¿Dónde debería empezar?
Ejecute huqan quickstart, inspeccione el Recibo de Confianza generado y luego lea la guía relevante para verificación, procedencia, política, aprobación, admisión de memoria, cobertura del Firewall de Acciones de Agente y supuestos de seguridad.
Mapa del repositorio
| Ruta | Propósito |
|---|---|
index.js, index.d.ts | Exportaciones del paquete y superficie de tipos pública |
kernel.js, graph.js | Núcleo de verificación y razonamiento de grafo |
lib/ | Puertas, procedencia, memoria, recibos, visor, adaptadores y módulos de soporte |
cli.js | Punto de entrada de CLI local |
server.js | Servidor REST local y entrega de UI |
mcpServer.js, bin/huqan-mcp.js | Integración MCP y binario del paquete |
public/ | UI local conectada al backend y visor de solo lectura |
test/ y *.test.js | Cobertura de pruebas automatizadas |
docs/ | Arquitectura, auditorías, contratos, límites de producto y hoja de ruta |
scripts/ | Conformidad, piloto, benchmark y herramientas del repositorio |
Desarrollo y verificación
Instale las dependencias y ejecute la suite de pruebas:
npm ci
npm test
Las comprobaciones enfocadas útiles incluyen:
npm run test:cli
npm run test:server
npm run test:plugin
npm run test:backup
npm run conformance:external
npm run conformance:a2a
npm run bench
npm run bench:verify
Si una prueba enfocada pasa, repórtela como evidencia para ese comportamiento enfocado. No la describa como evidencia de suite completa o de producción sin la prueba, CI y prueba de tiempo de ejecución correspondientes.
Documentación y soporte
- Hoja de ruta operativa actual
- Superficies de producto
- Posicionamiento competitivo
- Límite de PNL
- Paquete de verdad de escala
- Gobernanza
- Firewall de Acciones de Agente
- Guardián de acción externa
- Despliegue A2A
- Contrato de aprobación de carga HTTP
- Política de seguridad
- Contribución
- Problemas
- Discusiones
Evidencia y referencias
Las siguientes fuentes del repositorio definen el alcance actual y se prefieren sobre los resúmenes de marketing cuando una afirmación necesita verificación:
- Superficies de producto — UI local canónica, entrada de documentación y límites del Visor de Recibos de Confianza de solo lectura.
- Hoja de ruta operativa actual — orden de ejecución actual y limitaciones conocidas.
- Firewall de Acciones de Agente — límites de gobernanza de acciones compatibles.
- Despliegue A2A — condiciones y limitaciones de rutas limitadas por despliegue.
- Alcanzabilidad de módulos — distinción entre módulos alcanzables en producción y solo de biblioteca.
- Metadatos del paquete — versión del paquete, motor Node.js compatible, binarios y scripts.
Licencia
HUQAN se distribuye actualmente bajo la Licencia Pública General Affero de GNU v3.0, AGPL-3.0-only. Consulte LICENCIA y AVISO.
Se está preparando una licencia comercial separada para organizaciones que necesiten uso propietario de componentes cubiertos de HUQAN. Los términos comerciales aún no están operativos y este repositorio no otorga derechos comerciales. Contacte al propietario del proyecto solo después de que un acuerdo comercial aprobado esté disponible.
Las contribuciones externas futuras estarán sujetas al proceso de derechos de contribuyente aprobado del proyecto. CLA.md es actualmente el borrador de revisión versionado HUQAN-ICLA-v1.0-review y aún no es un acuerdo operativo. El contacto de revisión es Ali Ulu en aliulu@ai-ulu.com; publicar este contacto no otorga derechos ni activa un CLA. Consulte CONTRIBUTING.md para las reglas de contribución y revisión.
HUQAN: infraestructura local-first de confianza y evidencia para trabajo mediado por IA.