HUQAN

HUQAN

Confiança não é verdade. Verifique antes de confiar.

HUQAN é uma camada de governança e verificação de IA local-first, com confiança parcial, para alegações, gravações de memória e ações selecionadas de agentes. Ela conecta o trabalho assistido por IA a evidências, proveniência, escopo do workspace, políticas, aprovação, verificação, portões de risco, registros de auditoria e Recibos de Confiança.

HUQAN não é um LLM, um mecanismo universal de verdade ou uma promessa de que alucinações desaparecerão. Seu propósito é mais restrito e prático: tornar os fluxos de trabalho suportados de agentes de IA mais observáveis, revisáveis e responsabilizáveis antes que uma saída se torne uma entrada de memória, decisão ou ação no mundo real.

Início rápido · O que é HUQAN? · Como funciona · Capacidades · Formas de execução · FAQ · Escopo atual

Repositório canônico: https://github.com/ali-ulu/huqan

Um piloto limitado de Recibo de Confiança local — evidências, revisão, aprovação e contexto de auditoria; não é uma alegação de verdade universal ou prontidão para produção.

O que é HUQAN?

Sistemas de IA podem produzir saídas úteis enquanto deixam perguntas importantes sem resposta:

• Que evidências sustentam a alegação?
• Qual proveniência e escopo de workspace se aplicam?
• Uma gravação de memória ou ação arriscada foi revisada?
• Quais verificações de política e risco foram usadas?
• Por que o resultado foi permitido, bloqueado ou escalado?
• Que registro auditável permanece após a decisão?

HUQAN adiciona um limite de confiança limitado, determinístico e auditável em torno dessas perguntas em seus caminhos locais testados. Ela não torna o modelo subjacente verdadeiro por si só. Em vez disso, ajuda um desenvolvedor ou operador a inspecionar as evidências e o contexto da decisão antes de confiar em um resultado suportado.

Definição curta: HUQAN é uma infraestrutura de governança local-first para evidências, proveniência, políticas, aprovação, verificação e Recibos de Confiança em torno do trabalho assistido por IA.

Por que HUQAN?

A distinção central é entre um sistema de IA gerando uma saída e uma pessoa ou sistema confiando nessa saída. HUQAN foca no limite entre esses dois eventos.

Necessidade	Contribuição limitada da HUQAN
Rastreabilidade de evidências	Evidências com suporte em grafo, referências de proveniência, contexto de escopo e links de recibos
Verificações repetíveis	Verificação determinística, verificações de contradição e resultados de políticas em caminhos testados
Revisão de ações de agentes	Revisão, aprovação, simulação e limites de bloqueio em caminhos suportados, com escalonamento disponível onde um limite de aprovação está configurado
Memória protegida	Verificações de admissão e workspace antes de gravações canônicas de memória
Auditabilidade	Contexto de auditoria orientado a anexos, Recibos de Confiança canônicos e cadeias de recibos
Operação local-first	CLI, servidor REST local, MCP, biblioteca e superfícies de UI local sem exigir um modelo hospedado

Como 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

Nem todo resultado está disponível em todos os caminhos. O portão que protege chamadas de ferramentas responde allow, review, dry_run_only ou block; o portão de admissão de memória adiciona quarantine e reject, porque uma gravação pode ser mantida de lado para inspeção em vez de ser recusada diretamente.

Escalonamento é uma decisão que uma pessoa toma, não uma que o portão retorna. Onde um limite de aprovação está configurado, um revisor pode escalar um caso pendente em vez de decidi-lo: o caso passa para escalated e nada é executado até que a autoridade para a qual foi elevado decida. Esse é um controle multipartidário, então merece seu lugar em uma organização com mais de um aprovador e está simplesmente ausente em uma instalação de usuário único — não há segunda autoridade para elevar um caso. Os tipos de decisão são approve, reject, expire, cancel, escalate e override; veja lib/human-oversight-approval-runtime.js.

O fluxo principal de runtime local é:

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

Um resultado de verificação aprovado não é um certificado universal de verdade. É um resultado produzido dentro do limite configurado de evidências, proveniência, workspace, política e runtime.

Início rápido

Requisitos

Você precisa de Git, npm e Node.js 22.13.0 ou mais recente. Node.js 22 LTS ou 24 LTS é recomendado. Um conjunto de ferramentas de compilação pode ser necessário em plataformas que não podem usar um binário better-sqlite3 pré-compilado.

Instale o pacote publicado

npm install -g huqan

Isso instala dois comandos:

• huqan — a CLI local.
• huqan-mcp — o servidor MCP via stdio.

Nenhum dos comandos exige um arquivo de configuração ou chave de API apenas para iniciar.

Para uma execução única sem instalação global:

npx -y huqan quickstart

Execute a partir do código-fonte

git clone https://github.com/ali-ulu/huqan.git
cd huqan
npm ci
node cli.js quickstart

gh repo clone ali-ulu/huqan pode ser usado em vez de git clone.

Seu primeiro Recibo de Confiança

huqan quickstart

A partir de um checkout do código-fonte, use npm ci && node cli.js quickstart. O quickstart exercita o pipeline local: proponha uma mutação huqan.learn, receba uma decisão de revisão, persista a aprovação, realize a gravação canônica, verifique a alegação contra o grafo e imprima o Recibo de Confiança resultante.

A saída típica tem 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)

O quickstart usa um armazenamento descartável no diretório temporário. Ele não grava na sua própria memória e não relaxa nenhum portão.

Execute o piloto limitado de Recibo de Confiança

O repositório também contém um piloto limitado de Recibo de Confiança local:

npm run pilot:trust-receipt

Trate isso como um piloto e superfície de teste limitados, não como evidência de um ecossistema completo de confiança compartilhada ou prontidão universal para produção.

Instalação menor opcional

Ingestão de PDF (pdfjs-dist) e exportação de recibo em PDF (pdfkit) são dependências opcionais. Para omiti-las:

npm install -g huqan --omit=optional

Ler um PDF ou exportar um recibo como PDF então exige o pacote correspondente. A exportação de recibos em JSON e outros adaptadores permanecem caminhos separados.

Capacidades atuais

O repositório atual expõe os seguintes primitivos e superfícies de desenvolvedor. Cada capacidade permanece limitada pelo seu adaptador, política, workspace, aprovação e caminho de runtime específicos.

Capacidade	O que é documentado ou exercitado
Verificação com suporte em grafo	Alegações e relacionamentos podem ser verificados contra o grafo local em caminhos suportados
Evidências e proveniência	Fluxos de verificação e recibos preservam o contexto de fonte e decisão onde o caminho o fornece
Verificações de contradição	Caminhos de verificação suportados podem revelar evidências conflitantes em vez de tratar silenciosamente toda alegação como aceita
Relações explícitas	O limite atual de linguagem natural inclui marcadores CAUSES, PREVENTS, ENABLES e DEPENDS_ON
Admissão de memória	Gravações canônicas de memória passam por verificações de admissão e workspace
Portões de política e risco	Ações suportadas podem produzir resultados allow, block, review, escalate ou dry_run_only
Aprovação humana	Mutações protegidas podem exigir uma etapa de aprovação separada antes da gravação canônica ou caminho de ação
Recibos de Confiança	Registros canônicos de recibos preservam evidências limitadas, proveniência, decisão e contexto de auditoria
Prevenção de erros	A raiz do pacote expõe um núcleo de pré-verificação determinística e falha verificada
Primitivos de pacote	Primitivos de pacote .huqan existem com compatibilidade legada de leitor .axiom.json onde documentado
Superfícies de desenvolvedor	CLI, REST, MCP, biblioteca, UI local e superfícies somente leitura do Visualizador de Recibos de Confiança estão presentes
Transporte A2A	Quatro rotas são fornecidas, mas limitadas por implantação e não configuradas por padrão
Firewall de Ações de Agente	Caminhos de propriedade da HUQAN mais o contrato de pré-execução huqan-gate independente de agente; a aplicação externa existe apenas onde um hook ou wrapper de cliente está realmente conectado

Formas de execução

Como biblioteca

const Kernel = require('huqan'); // KernelV2, the canonical runtime
const kernel = new Kernel();

require('huqan') resolve para KernelV2, o runtime usado pela CLI, servidor REST e servidor MCP. A superfície de compatibilidade mais antiga KernelV1 permanece acessível como require('huqan').KernelV1, mas está obsoleta e não é a opção canônica de runtime.

A raiz do pacote também expõe o núcleo de Prevenção de Erros:

const { createErrorPrevention } = require('huqan');
const prevention = createErrorPrevention(kernel.memory, {
  verifyEvidence,
  resolveApproval,
});

Esta é uma superfície de pacote/biblioteca para memória de falha verificada, ciclo de vida de regras governadas e decisões determinísticas de pré-verificação. Não é uma ferramenta MCP adicional.

CLI local

npm start

A invocação direta permanece disponível:

node cli.js

HUQAN atualmente lida com marcadores explícitos de relações suportadas. Não é um mecanismo de compreensão de linguagem natural de propósito geral.

Servidor REST local

Endpoints de mutação exigem uma chave de API:

HUQAN_API_KEY=replace-with-a-secret npm run server

O servidor inicia em http://localhost:3000.

Endpoints úteis incluem:

Endpoint	Método	Propósito
/health	GET	Verificação de saúde
/api?q=...	GET	Superfície de consulta somente leitura na lista de permissões
/graph-data	GET	Exportação do grafo de conhecimento
/verify	POST	Verificação protegida
/v2/verify	POST	Verificação estruturada protegida
/upload	POST	Carregamento de alias protegido

Solicitações de mutação autenticadas usam X-API-Key ou Authorization: Bearer <key>. Revise o contrato de rota e a política de autorização do workspace antes de expor um servidor local além do seu limite pretendido.

Servidor MCP para Claude ou Cursor

huqan-mcp

Configuração do Claude Desktop sem instalação global prévia:

{
  "mcpServers": {
    "huqan": {
      "command": "npx",
      "args": ["-y", "--package=huqan", "huqan-mcp"]
    }
  }
}

--package=huqan é necessário porque o nome do binário difere do nome do pacote. A partir de um checkout do código-fonte, use "command": "node" com "args": ["/absolute/path/to/huqan/mcpServer.js"].

O catálogo MCP visível ao modelo inclui ferramentas para aprendizado, perguntas fundamentadas, verificação, planejamento, execução limitada de agentes, pré-visualização/status de ingestão, inspeção de políticas, rastros de raciocínio, comparação, geração de hipóteses, advocacia, busca com escopo, leitura de Recibos de Confiança e síntese recursiva de conhecimento (huqan.fractal-learn, opcionalmente auto-ajustável através do seu modo unidirecional autoTune — pode apertar seus próprios limites, mas nunca afrouxá-los).

huqan.self-evolve executa o mesmo loop de síntese e depois uma passagem medida de auto-evolução, e relata qual dos dois mudou: seu veredito distingue uma execução que apenas alterou o conteúdo do grafo (native-content-only) de uma que também alterou os limites que o produzem (native-writes-config), com inactive quando nada mudou. É classificado como uma gravação mutante e é retido para revisão humana exatamente como huqan.fractal-learn, então o alcance que adiciona está no que uma execução aprovada pode mudar, não no que pode contornar.

Ferramentas exclusivas de operador são deliberadamente retidas de tools/list e exigem HUQAN_MCP_OPERATOR_TOKEN:

Ferramenta	Propósito
huqan.approve	Aprovar ou rejeitar uma aprovação pendente
huqan.approvals	Listar aprovações pendentes
huqan.agent_resume	Retomar uma execução de agente suspensa

Essa separação significa que um modelo que propõe uma ação mutante não pode também aprová-la através do catálogo visível ao modelo.

Capacidades de operador são de uso único, e o registro de uma capacidade gasta é durável (#1674). Nonces consumidos são gravados em .huqan-capability-nonces ao lado do armazenamento de memória, então uma capacidade já usada permanece usada após reinicialização e entre workers; defina HUQAN_MCP_CAPABILITY_NONCE_DIR para apontar cada worker para um diretório gravável compartilhado quando o padrão não estiver em armazenamento compartilhado. Se esse diretório não puder ser gravado, a verificação de capacidade falha de forma fechada em vez de recorrer à proteção de repetição apenas em memória.

UI local e Visualizador de Recibos de Confiança

Inicie o servidor local para servir a UI de desenvolvedor conectada ao backend:

npm run server

A interface local canônica é public/index.html. O Visualizador de Recibos de Confiança somente leitura está disponível em /viewer em um servidor em execução e renderiza recibos já pertencentes a esse servidor local. Ele não é uma superfície de mutação e não é uma demonstração estática pública de marketing.

Para um passo a passo de observabilidade cobrindo telemetria de servidor local, uso de ferramentas, alertas, estado de fila e etapas de painel, consulte Observability Quickstart. Para integração de ciclo de vida de framework por meio do cliente de telemetria local estável, consulte Observability Telemetry Client.

Acelerador de grafo Rust opcional

O repositório contém um acelerador huqan-core Rust JSON-IPC opcional. Ele não é necessário para o caminho normal de CLI, servidor, MCP ou canônico kernel.learn(). Quando o binário não está disponível, o caminho JavaScript permanece como o comportamento de referência.

cd huqan-core
cargo build --release
cd ..

Para selecionar um binário em outro local, defina HUQAN_RUST_BIN antes de iniciar o Node. Compare o caminho opcional com:

node benchmarks/rust-vs-js-graph.js 2000

O benchmark não alega throughput Rust quando nenhum binário está presente.

Escopo atual

HUQAN é atualmente uma camada de governança de confiança parcial local-first. O projeto é mais forte onde pode observar um fluxo suportado, anexar evidências e proveniência, avaliar portões configurados, exigir aprovação quando aplicável e criar um registro de auditoria ou Recibo de Confiança limitado.

Entregue e limitado

O repositório contém primitivas de verificação local, grafo, proveniência, aprovação, auditoria, recibo, memória, portão de ação, CLI, REST, MCP, UI e pacote. Ele também contém duas suítes de conformidade executadas no repositório:

npm run conformance:external
npm run conformance:a2a

Essas suítes são evidências para os casos testados e implementações que cobrem. Elas não são certificação de terceiros ou prova de interoperabilidade universal.

O pacote também inclui huqan-gate, um guarda de pré-execução independente de marca de agente. Seu envelope genérico permite que um agente futuro reutilize a mesma política sem adicionar o nome desse agente ao núcleo. Projeções Claude Code, Codex, OpenCode, Pi e Hermes estão incluídas. Isso é aplicação somente quando o cliente realmente chama o guarda antes da execução; clientes sem hook exigem um wrapper, gateway ou sandbox. Consulte External action guard.

Rotas A2A são controladas por implantação

Quatro rotas são montadas por meio de lib/a2a/routes.js:

• POST /api/a2a/exchange
• GET /.well-known/agent-card.json
• POST /api/a2a/negotiate
• GET /api/a2a/tasks/{taskId}

Com HUQAN_A2A_AUTHORITY_FILE e HUQAN_A2A_REPLAY_DIR não definidos, as rotas respondem 404 em vez de 401; portanto, uma instalação não configurada não anuncia uma superfície que não pode atender. A rota de troca tem condições adicionais de pacote/tempo de execução documentadas em A2A deployment.

Implementado, mas não alcançável em produção

Alguns módulos são implementados e testados por unidade, mas não são alcançados pelo grafo de ponto de entrada de produção declarado em lib/module-reachability.js. Um teste de unidade aprovado para tal módulo prova apenas comportamento isolado; não prova que o produto instalado executa esse módulo.

O relatório de alcançabilidade atual inclui entradas limitadas de V5, Self-Healer e conector. Consulte o relatório ao vivo e Current Operating Roadmap antes de descrever qualquer um deles como geralmente disponível.

O que HUQAN não alega

HUQAN não alega:

• verdade universal ou eliminação de alucinações de IA;
• aplicação inline completa para cada conector, agente ou caminho de mutação;
• um ecossistema de confiança compartilhada V5 finalizado;
• interoperabilidade externa de terceiros para o transporte A2A;
• um mercado público de agentes, rede de certificação, selo público ou economia de reputação;
• desempenho de grafo em escala Wikipedia;
• um Self-Healer autônomo completo;
• que um documento de design, roteiro ou teste de unidade isolado é equivalente a evidência de implantação em produção;
• que HUQAN substitui IAM, segurança de aplicativos, segurança de infraestrutura, proteção de dados ou governança humana.

FAQ

HUQAN é um modelo de IA?

Não. HUQAN é uma camada de governança e verificação local-first em torno de fluxos de trabalho assistidos por IA suportados. Ele não substitui o modelo de linguagem que gerou uma saída.

HUQAN elimina alucinações?

Não. HUQAN não promete eliminar alucinações. Ele ajuda um fluxo de trabalho suportado a inspecionar evidências e proveniência, aplicar políticas configuradas e limites de aprovação, e registrar o contexto de decisão resultante.

O que é um Recibo de Confiança?

Um Recibo de Confiança é um registro limitado e auditável de um fluxo de verificação ou governança de ação suportado. Ele pode preservar evidências, proveniência, escopo, risco, revisão, aprovação e a decisão resultante. Não é um certificado universal de que uma afirmação é verdadeira.

HUQAN pode bloquear uma ação de agente?

Em caminhos de execução suportados e conectados, HUQAN pode produzir decisões como allow, review, dry_run_only ou block. Agentes externos podem usar o envelope comum huqan-gate e adaptadores atuais, mas o hook ou wrapper deve ser instalado antes da execução. A cobertura deve ser verificada para o cliente, conector, caminho de mutação, identidade, política e configuração de implantação específicos. HUQAN não alega que um agente não conectado ou sem hook é aplicado.

HUQAN substitui segurança empresarial?

Não. HUQAN complementa gerenciamento de identidade e acesso, segurança de aplicativos, segurança de infraestrutura, proteção de dados e supervisão humana. Ele não substitui esses controles.

HUQAN pode ser executado localmente sem um modelo hospedado?

O núcleo de grafo local, verificação, portão e recibo não requer um modelo hospedado ou serviço em nuvem. Adaptadores opcionais, integrações e superfícies controladas por implantação podem ter seus próprios requisitos.

O que significa "confiança parcial"?

Significa que um resultado é avaliado dentro de limites explícitos de evidência, proveniência, espaço de trabalho, política, aprovação e tempo de execução. HUQAN não trata cada saída de modelo, entrada de memória, conector ou ação externa como automaticamente confiável.

Por onde devo começar?

Execute huqan quickstart, inspecione o Recibo de Confiança gerado e, em seguida, leia o guia relevante para verificação, proveniência, política, aprovação, admissão de memória, cobertura do Agent Action Firewall e premissas de segurança.

Mapa do repositório

Caminho	Propósito
index.js, index.d.ts	Exportações de pacote e superfície de tipo público
kernel.js, graph.js	Núcleo de verificação e raciocínio de grafo
lib/	Portões, proveniência, memória, recibos, visualizador, adaptadores e módulos de suporte
cli.js	Ponto de entrada CLI local
server.js	Servidor REST local e entrega de UI
mcpServer.js, bin/huqan-mcp.js	Integração MCP e binário de pacote
public/	UI local conectada ao backend e visualizador somente leitura
test/ e *.test.js	Cobertura de teste automatizado
docs/	Arquitetura, auditorias, contratos, limites de produto e roteiro
scripts/	Conformidade, piloto, benchmark e ferramentas de repositório

Desenvolvimento e verificação

Instale as dependências e execute a suíte de testes:

npm ci
npm test

Verificações focadas úteis incluem:

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

Se um teste focado passar, relate-o como evidência para esse comportamento focado. Não o descreva como evidência de suíte completa ou produção sem a prova correspondente de teste, CI e tempo de execução.

Documentação e suporte

• Current operating roadmap
• Product surfaces
• Competitive positioning
• NLP boundary
• Scale truth pack
• Governance
• Agent Action Firewall
• External action guard
• A2A deployment
• HTTP upload approval contract
• Security policy
• Contributing
• Issues
• Discussions

Evidências e referências

As seguintes fontes do repositório definem o escopo atual e são preferidas em relação a resumos de marketing quando uma afirmação precisa de verificação:

1. Product surfaces — interface local canônica, entrada de docs e limites do Visualizador de Recibos de Confiança somente leitura.
2. Current operating roadmap — ordem de execução atual e limitações conhecidas.
3. Agent Action Firewall — limites suportados de governança de ação.
4. A2A deployment — condições e limitações de rota controladas por implantação.
5. Module reachability — distinção entre módulos alcançáveis em produção e somente biblioteca.
6. Package metadata — versão do pacote, engine Node.js suportado, binários e scripts.

Licença

HUQAN é atualmente distribuído sob a GNU Affero General Public License v3.0, AGPL-3.0-only. Consulte LICENSE e NOTICE.

Uma licença comercial separada está sendo preparada para organizações que precisam de uso proprietário de componentes cobertos do HUQAN. Os termos comerciais ainda não estão operacionais e nenhum direito comercial é concedido por este repositório. Entre em contato com o proprietário do projeto somente após um acordo comercial aprovado estar disponível.

Contribuições externas futuras estarão sujeitas ao processo de direitos de contribuidor aprovado do projeto. CLA.md é atualmente o rascunho de revisão versionado HUQAN-ICLA-v1.0-review e ainda não é um acordo operacional. O contato de revisão é Ali Ulu em aliulu@ai-ulu.com; publicar este contato não concede direitos ou ativa um CLA. Consulte CONTRIBUTING.md para as regras de contribuição e revisão.

---

HUQAN: infraestrutura local-first de confiança e evidência para trabalho mediado por IA.