@orkastery/cli 0.5.0 → 0.5.3

package/dist/intelligence-graph-cli.js

@@ -33,7 +33,10 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.USO_DO_GRAFO = exports.AMOSTRA_SCHEMA = exports.STATUS_SCHEMA = void 0;
+exports.CORRECAO_DO_INDICE = exports.USO_DO_GRAFO = exports.AMOSTRA_SCHEMA = exports.STATUS_SCHEMA = void 0;
+exports.descreverVersoes = descreverVersoes;
+exports.correcaoDosAnalisadores = correcaoDosAnalisadores;
+exports.checarAnalisadoresDoGrafo = checarAnalisadoresDoGrafo;
 exports.lerPedido = lerPedido;
 exports.executarGrafo = executarGrafo;
 /**
@@ -46,34 +49,96 @@ exports.executarGrafo = executarGrafo;
  * O argv chega cru e o parser e estrito: subcomando conhecido, opcao conhecida uma vez so, valor
  * onde a opcao pede valor e bandeira sem valor, numero exato de posicionais. Resposta sai 0, mesmo
  * vazia; erro tipado sai 1 e, com `--json`, vem como objeto.
+ *
+ * RM-031 KG5 (D4, D5): `--teto-bytes N` limita a resposta em bytes (JSON compacto), para quem a leva
+ * ao contexto de um agente, como as tools `ork_grafo_*` do MCP; sem a opcao, a saida e a de antes. Sem
+ * o indice do HEAD, a recusa diz se ha indice de outra revisao ou de outro extrator, e a correcao.
  */
 const node_crypto_1 = require("node:crypto");
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const intelligence_graph_contract_1 = require("./intelligence-graph-contract");
 const intelligence_graph_index_1 = require("./intelligence-graph-index");
+const intelligence_graph_parsers_1 = require("./intelligence-graph-parsers");
 const intelligence_graph_query_1 = require("./intelligence-graph-query");
 const intelligence_graph_repo_1 = require("./intelligence-graph-repo");
+const intelligence_graph_contexto_1 = require("./intelligence-graph-contexto");
 exports.STATUS_SCHEMA = 'ork.code-graph-index-status/v0';
+/** As versoes dos analisadores como o `ork grafo status` e o `ork doctor` as mostram. */
+function descreverVersoes(v) {
+    return Object.entries(v).map(([k, x]) => `${k} ${x}`).join(', ');
+}
+/** O prefixo das recusas dos analisadores (`intelligence-graph-parsers.ts`). */
+const RECUSA_DOS_ANALISADORES = 'grafo.parser.indisponivel';
+/**
+ * RM-031 (pacote do npm): o que fazer quando os analisadores nao carregam, dito pelo `ork doctor` e
+ * pelo `ork grafo status`. O micromark e so ESM e carrega por `require`, o que o Node so faz sem flag
+ * a partir de 20.19 e de 22.12. Nos outros casos o pacote falta ou esta fora da instalacao do `ork`,
+ * e a instalacao global do npm traz os analisadores, que sao dependencias do pacote. Mora aqui, fora
+ * de `MODULOS_DO_EXTRATOR`, para a redacao nao entrar na chave do indice; a versao vem de quem chama
+ * (o `index.ts`), porque o CLI do grafo so importa a propria familia (fronteira do KG3).
+ */
+function correcaoDosAnalisadores(motivo, versao) {
+    if (/ERR_REQUIRE_ESM/.test(motivo)) {
+        return `o micromark e so ESM, e este Node (${process.version}) nao o carrega por require: use Node 20.19, 22.12 ou mais novo, ` +
+            'sem a opcao --no-experimental-require-module (na linha de comando ou no NODE_OPTIONS)';
+    }
+    // Sem a versao do pacote (`0.0.0-desconhecida` quando o package.json dele nao e achado), o comando
+    // sai sem `@<versao>` e o npm instala a ultima publicada.
+    const fixada = versao && /^\d+\.\d+\.\d+/.test(versao) && !versao.startsWith('0.0.0') ? `@${versao}` : '';
+    return `reinstale o ork global, que traz os analisadores como dependencias: npm install -g @orkastery/cli${fixada}` +
+        ' (instalado dentro de um projeto ou pelo npx, o npm deixa os analisadores fora do pacote do ork, e o grafo os recusa)';
+}
+/**
+ * RM-031 (pacote do npm): o check "analisadores do grafo" do `ork doctor`. Carrega o que o
+ * `ork grafo indexar` carrega (`carregarAnalisadores`), entao diz o que o indexar faria, inclusive no
+ * Node sem `require` de ESM. A falta e `warn`, com a correcao: o grafo nao e condicao do despacho de
+ * fase. Fora da familia do grafo so o `index.ts` e o worker do MCP a abrem (fronteira do KG1), entao o
+ * `index.ts` passa este check ao doctor, que nao importa o grafo.
+ */
+function checarAnalisadoresDoGrafo(versao, carregar = intelligence_graph_parsers_1.carregarAnalisadores, versoes = intelligence_graph_parsers_1.versoesDosAnalisadores) {
+    const nome = 'analisadores do grafo';
+    try {
+        carregar();
+        return { nome, nivel: 'ok', detalhe: descreverVersoes(versoes()) };
+    }
+    catch (e) {
+        const motivo = e.message;
+        return { nome, nivel: 'warn',
+            detalhe: `${motivo}: o ork grafo indexar recusa nesta instalacao, e sem o indice as consultas e as tools ork_grafo_* tambem`,
+            correcao: correcaoDosAnalisadores(motivo, versao) };
+    }
+}
 /** O mesmo schema da amostra do KG2: as amostras auditadas continuam validas. */
 exports.AMOSTRA_SCHEMA = 'ork.graph-edge-audit-sample/v0';
 exports.USO_DO_GRAFO = [
     'uso: ork grafo indexar [--verificar] [--forcar] [--json]',
     '     ork grafo status [--json]',
-    '     ork grafo vizinhos <no> [--profundidade N] [--sentido entrada|saida|ambos] [--tipo T,...] [--limite N] [--json]',
-    '     ork grafo chamadores <simbolo> [--profundidade N] [--limite N] [--json]',
-    '     ork grafo importadores <arquivo|simbolo> [--profundidade N] [--limite N] [--json]',
-    '     ork grafo caminho <de> <para> [--sentido saida|entrada|ambos] [--tipo T,...] [--json]',
+    '     ork grafo contexto <thread> [--json [--teto-bytes N]]',
+    '     ork grafo vizinhos <no> [--profundidade N] [--sentido entrada|saida|ambos] [--tipo T,...] [--limite N] [--json [--teto-bytes N]]',
+    '     ork grafo chamadores <simbolo> [--profundidade N] [--limite N] [--json [--teto-bytes N]]',
+    '     ork grafo importadores <arquivo|simbolo> [--profundidade N] [--limite N] [--json [--teto-bytes N]]',
+    '     ork grafo caminho <de> <para> [--sentido saida|entrada|ambos] [--tipo T,...] [--json [--teto-bytes N]]',
     '     ork grafo amostra [--por-estrato N] | ork grafo amostra --conferir ARQ [--json]',
     '     ork grafo limpar [--tudo] [--json]',
 ].join('\n');
+/** KG5 (D5): a correcao das recusas de indice que a proxima indexacao resolve. */
+exports.CORRECAO_DO_INDICE = 'ork grafo indexar';
+/** KG5 (D5): o estado do indice do HEAD que cada recusa declara no JSON, ao lado da correcao. */
+const ESTADO_DO_INDICE = Object.freeze({
+    'grafo.indice.ausente': 'nao-indexado',
+    'grafo.indice.outra-revisao': 'outra-revisao',
+    'grafo.indice.outro-extrator': 'outro-extrator',
+    'grafo.indice.corrompido': 'corrompido',
+});
 const SUBCOMANDOS = Object.freeze({
     indexar: { posicionais: 0, bandeiras: ['verificar', 'forcar', 'json'], valores: [] },
     status: { posicionais: 0, bandeiras: ['json'], valores: [] },
-    vizinhos: { posicionais: 1, bandeiras: ['json'], valores: ['profundidade', 'sentido', 'tipo', 'limite'] },
-    chamadores: { posicionais: 1, bandeiras: ['json'], valores: ['profundidade', 'limite'] },
-    importadores: { posicionais: 1, bandeiras: ['json'], valores: ['profundidade', 'limite'] },
-    caminho: { posicionais: 2, bandeiras: ['json'], valores: ['sentido', 'tipo'] },
+    contexto: { posicionais: 1, bandeiras: ['json'], valores: ['teto-bytes'] },
+    vizinhos: { posicionais: 1, bandeiras: ['json'], valores: ['profundidade', 'sentido', 'tipo', 'limite', 'teto-bytes'] },
+    chamadores: { posicionais: 1, bandeiras: ['json'], valores: ['profundidade', 'limite', 'teto-bytes'] },
+    importadores: { posicionais: 1, bandeiras: ['json'], valores: ['profundidade', 'limite', 'teto-bytes'] },
+    caminho: { posicionais: 2, bandeiras: ['json'], valores: ['sentido', 'tipo', 'teto-bytes'] },
     amostra: { posicionais: 0, bandeiras: ['json'], valores: ['por-estrato', 'conferir'] },
     limpar: { posicionais: 0, bandeiras: ['tudo', 'json'], valores: [] },
 });
@@ -141,8 +206,40 @@ function sentido(p) {
         uso(`--sentido desconhecido: ${v}`);
     return v;
 }
+/** KG5 (D4): o teto vale para o JSON, que e o que vai ao contexto de quem consulta. */
+function tetoDeBytes(p) {
+    const teto = inteiro(p, 'teto-bytes');
+    if (teto === undefined)
+        return undefined;
+    if (!p.bandeiras.has('json'))
+        uso('--teto-bytes exige --json');
+    if (teto < 1)
+        uso('--teto-bytes precisa ser ao menos 1');
+    return teto;
+}
 const mb = (bytes) => `${(bytes / 1024 / 1024).toFixed(1)} MB`;
 const contagem = (o) => Object.entries(o).map(([k, v]) => `${k}=${v}`).join(' ');
+/** Ate cinco caminhos e quantos ficaram de fora. */
+const alguns = (lista) => (lista.length ? ` (${lista.slice(0, 5).join(', ')}${lista.length > 5 ? ` e mais ${lista.length - 5}` : ''})` : '');
+/** KG4: como a extracao rodou, a base e o que veio dela, ou por que foi completa. */
+function linhasDaExtracao(r) {
+    if (r.modo === null)
+        return [];
+    const a = r.reaproveitamento;
+    if (r.modo === 'incremental' && r.base && a) {
+        // Desestruturado: o lint de horario le o campo de nome curto do TypeScript como instante.
+        const { ts: doTs, md: doMd, mudanca } = a;
+        const ts = doTs.modo === 'inteiro' ? `TypeScript inteiro (${doTs.motivo})`
+            : doTs.modo === 'parcial' ? `TypeScript parcial, ${doTs.reextraidos.length} reextraido(s)${alguns(doTs.reextraidos)} num programa de ${doTs.programa}, ${doTs.reaproveitados} da base`
+                : `TypeScript todo da base (${doTs.reaproveitados})`;
+        return [
+            `  extracao     incremental a partir do indice de ${r.base.revision.slice(0, 12)}: ${mudanca.alterados} alterado(s), ${mudanca.novos} novo(s), ${mudanca.removidos} removido(s)`,
+            `               ${ts}`,
+            `               Markdown: ${doMd.reextraidos.length} reextraido(s)${alguns(doMd.reextraidos)}, ${doMd.reaproveitados} da base`,
+        ];
+    }
+    return [`  extracao     completa${r.motivo_completo ? `: ${r.motivo_completo}` : ''}`];
+}
 function indexar(ctx, p) {
     const r = (0, intelligence_graph_index_1.construirIndice)(ctx, { verificar: p.bandeiras.has('verificar'), forcar: p.bandeiras.has('forcar') });
     if (p.bandeiras.has('json')) {
@@ -159,12 +256,18 @@ function indexar(ctx, p) {
         `  conferencia  conferirFontes verificada: ${m.conferencia.fontes} fontes e ${m.conferencia.evidencias} evidencias contra os bytes`,
         `  nos          ${contagem(m.contagens.nos)}`,
         `  arestas      ${contagem(m.contagens.arestas)}`,
-        `  lugar        ${r.dir} (${mb(m.graph_bytes + m.report_bytes)})`,
+        `  lugar        ${r.dir} (${mb(m.graph_bytes + m.report_bytes + m.units_bytes)})`,
+        ...linhasDaExtracao(r),
     ];
     if (r.motivo)
         linhas.push(`  motivo       ${r.motivo}`);
-    for (const d of r.determinismo ?? [])
-        linhas.push(`  determinismo ${d.ordem}: digest ${d.digest.slice(0, 16)}, relatorio ${d.relatorio.slice(0, 16)}, ${d.igual ? 'igual' : 'DIFERENTE'}`);
+    for (const d of r.determinismo ?? []) {
+        linhas.push(`  determinismo ${d.ordem}: digest ${d.digest.slice(0, 16)}, relatorio ${d.relatorio.slice(0, 16)}, unidades ${d.unidades.slice(0, 16)}, ${d.igual ? 'igual' : 'DIFERENTE'}`);
+    }
+    if (r.incremental)
+        linhas.push(`  incremental  a partir do indice de ${r.incremental.base.slice(0, 12)}: ${r.incremental.igual ? 'igual a completa nos quatro arquivos' : 'DIFERENTE'}`);
+    else if (r.determinismo)
+        linhas.push(`  incremental  nao conferido: ${r.motivo_completo ?? 'sem base'}`);
     linhas.push(`  tempo        ${r.ms} ms`);
     if (r.determinismo)
         linhas.push('aprovado');
@@ -187,9 +290,11 @@ function status(ctx, p) {
     const doHead = chave ? estado.indices.find((i) => i.chave === chave) ?? null : null;
     // Sem analisadores nao ha chave: o indice do HEAD fica indisponivel, nunca "ausente" (indexar tambem nao roda).
     const indiceDoHeadEstado = erro ? 'indisponivel' : doHead ? (doHead.problema ? 'com-problema' : 'presente') : 'ausente';
+    // RM-031 (pacote do npm): a recusa dos analisadores vem com o que fazer, a mesma correcao do `ork doctor`.
+    const correcao = erro !== null && erro.startsWith(RECUSA_DOS_ANALISADORES) ? correcaoDosAnalisadores(erro, ctx.versao) : null;
     const r = {
         schema: exports.STATUS_SCHEMA, head: arvore.head, arvore: arvore.motivo === null ? 'limpa' : arvore.motivo, chave_do_head: chave,
-        indice_do_head: indiceDoHeadEstado, analisadores, erro,
+        indice_do_head: indiceDoHeadEstado, analisadores, erro, correcao,
         dir: estado.dir, bytes: estado.bytes, indices: estado.indices, sobras: estado.sobras,
     };
     if (p.bandeiras.has('json')) {
@@ -199,8 +304,11 @@ function status(ctx, p) {
     const linhas = [
         `grafo: HEAD ${arvore.head ? arvore.head.slice(0, 12) : 'sem commit'}, arvore ${r.arvore}`,
         `  indice do HEAD  ${chave ?? 'indisponivel'} ${r.indice_do_head === 'ausente' ? '(ausente: rode ork grafo indexar)'
-            : r.indice_do_head === 'indisponivel' ? '(sem os analisadores nesta instalacao, nem a consulta nem o indexar rodam)' : `(${r.indice_do_head})`}`,
-        `  analisadores    ${erro ?? Object.entries(analisadores).map(([k, v]) => `${k} ${v}`).join(', ')}`,
+            : r.indice_do_head === 'indisponivel'
+                ? (correcao ? '(sem os analisadores nesta instalacao, nem a consulta nem o indexar rodam)' : '(sem a chave do indice: o erro esta na linha de baixo)')
+                : `(${r.indice_do_head})`}`,
+        `  analisadores    ${erro ?? descreverVersoes(analisadores)}`,
+        ...(correcao ? [`  correcao        ${correcao}`] : []),
         `  pasta           ${estado.dir ?? 'ainda nao criada'} (${estado.indices.length} indice(s), ${mb(estado.bytes)})`,
     ];
     for (const i of estado.indices) {
@@ -211,9 +319,65 @@ function status(ctx, p) {
     ctx.escrever(linhas.join('\n'));
     return 0;
 }
+/**
+ * KG5 (CHECK rodada 1, A1): o que difere entre o extrator do indice guardado e o de quem consulta. A
+ * versao do Node entra no rotulo do analisador de JavaScript, entao outra instalacao ou outro Node dao
+ * outra chave com o mesmo conteudo.
+ */
+function diferencasDoExtrator(guardado, atual) {
+    const r = [];
+    for (const k of Object.keys(atual.analisadores).sort(intelligence_graph_contract_1.compararUtf8)) {
+        const antes = guardado.analisadores?.[k];
+        if (antes !== atual.analisadores[k])
+            r.push(`${k} ${antes ?? '?'} no indice, ${atual.analisadores[k]} aqui`);
+    }
+    if ((0, intelligence_graph_contract_1.canonico)(guardado.pacotes) !== (0, intelligence_graph_contract_1.canonico)(atual.pacotes))
+        r.push('pacotes dos analisadores');
+    if (guardado.codigo !== atual.codigo)
+        r.push('codigo do extrator');
+    return r;
+}
+/**
+ * KG5 (D5): sem o indice do HEAD, diz o que ha no lugar. Indice guardado do mesmo repositorio e da
+ * revisao do HEAD com outra chave e de outro extrator (instalacao, Node, analisadores ou codigo do
+ * extrator mudaram), e a recusa diz o que mudou; de outra revisao, e indice velho ou de outra arvore.
+ * Nos dois casos a correcao e indexar de novo, com a instalacao de quem consulta; sem nenhum, fica a
+ * recusa original (nao indexado). Nunca responde por um indice que nao e o do HEAD.
+ */
+function semIndiceDoHead(ctx, original) {
+    const arvore = (0, intelligence_graph_repo_1.revisaoDaArvore)(ctx.raiz);
+    if (!arvore.head)
+        throw original;
+    const perfil = (0, intelligence_graph_index_1.perfilDoIndice)(arvore.raiz, undefined, ctx.repositorio ? { repository_id: ctx.repositorio } : {});
+    const chave = (0, intelligence_graph_index_1.chaveDoIndice)(arvore.head, perfil), head = arvore.head.slice(0, 12);
+    const guardados = (0, intelligence_graph_index_1.estadoDosIndices)(ctx).indices
+        .filter((i) => i.problema === null && i.chave !== chave && i.repository_id === perfil.repository_id && i.revision !== null);
+    const doHead = guardados.find((i) => i.revision === arvore.head);
+    if (doHead) {
+        const diferencas = diferencasDoExtrator((0, intelligence_graph_index_1.lerIndice)(ctx, doHead.chave, { grafo: false }).manifesto, perfil);
+        throw new Error(`grafo.indice.outro-extrator: ha indice do HEAD ${head} de outro extrator (${diferencas.join('; ') || 'perfil diferente'}); `
+            + `rode ${exports.CORRECAO_DO_INDICE} com a mesma instalacao do ork e o mesmo Node de quem consulta (o servidor MCP consulta com a dele)`);
+    }
+    if (guardados.length) {
+        const revisoes = [...new Set(guardados.map((i) => i.revision.slice(0, 12)))].sort(intelligence_graph_contract_1.compararUtf8);
+        // CHECK rodada 2 (N7): a ressalva da instalacao ja na primeira recusa, a de cada commit do GO.
+        throw new Error(`grafo.indice.outra-revisao: o HEAD ${head} nao tem indice; o guardado e de outra revisao${alguns(revisoes)}; `
+            + `rode ${exports.CORRECAO_DO_INDICE} com a mesma instalacao do ork e o mesmo Node de quem consulta`);
+    }
+    throw original;
+}
 /** O indice do HEAD pronto para consulta, com a concessao local e o cabecalho; `grafo` ja vem filtrado por ela. */
 function consultavel(ctx) {
-    const { arvore, perfil, chave, indice } = (0, intelligence_graph_index_1.indiceDoHead)(ctx);
+    let doHead;
+    try {
+        doHead = (0, intelligence_graph_index_1.indiceDoHead)(ctx);
+    }
+    catch (e) {
+        if (String(e.message).startsWith('grafo.indice.ausente'))
+            semIndiceDoHead(ctx, e);
+        throw e;
+    }
+    const { arvore, perfil, chave, indice } = doHead;
     const concessao = (0, intelligence_graph_index_1.concessaoLocal)(arvore.raiz, perfil);
     const grafo = (0, intelligence_graph_query_1.filtrarGrafo)(indice.grafo, concessao), m = indice.manifesto;
     const cabecalho = {
@@ -227,18 +391,82 @@ function responder(ctx, p, r) {
     ctx.escrever(p.bandeiras.has('json') ? (0, intelligence_graph_query_1.jsonDaResposta)(r) : (0, intelligence_graph_query_1.textoDaResposta)(r));
     return 0;
 }
+/**
+ * KG5 (D4): a resposta em JSON compacto que cabe em `teto` bytes. Se a pedida nao cabe, vale o maior
+ * limite que cabe: as arestas mais longe do alvo saem primeiro, pela mesma ordem do `--limite`, e
+ * `consulta.limite` passa a ser o efetivo. O tamanho cresce com o limite (cada aresta a mais so soma
+ * bytes), entao a busca binaria acha o maior que cabe, sempre o mesmo. Aresta nunca sai sem toda a
+ * evidencia; o caminho nao se corta.
+ */
+function respostaComTeto(perguntar, limite, teto) {
+    const pedida = perguntar(limite);
+    const limitePedido = pedida.consulta.limite;
+    const comTeto = (r, cortado) => JSON.stringify({ ...r, teto: { bytes: teto, limite_pedido: limitePedido, cortado } });
+    const inteira = comTeto(pedida, false);
+    if (Buffer.byteLength(inteira) <= teto)
+        return inteira;
+    const ehCaminho = pedida.consulta.tipo === 'caminho';
+    // So chega aqui o que nao cabe nem com a aresta mais perto do alvo: estreitar a consulta nao ajuda.
+    const excedido = (resposta, bytes) => {
+        throw new intelligence_graph_query_1.ErroDeConsulta('grafo.consulta.teto-excedido', `${resposta} tem ${bytes} bytes, acima do teto de ${teto}; ${ehCaminho ? 'o caminho nao se corta: ' : ''}use --teto-bytes maior`);
+    };
+    if (ehCaminho)
+        excedido(`o caminho de ${pedida.arestas.length} passo(s)`, Buffer.byteLength(inteira));
+    if (pedida.arestas.length <= 1)
+        excedido(`a resposta com ${pedida.arestas.length} aresta(s)`, Buffer.byteLength(inteira));
+    let menor = 1, maior = pedida.arestas.length - 1, melhor = null;
+    while (menor <= maior) {
+        const k = Math.floor((menor + maior) / 2), texto = comTeto(perguntar(k), true);
+        if (Buffer.byteLength(texto) <= teto) {
+            melhor = texto;
+            menor = k + 1;
+        }
+        else
+            maior = k - 1;
+    }
+    return melhor ?? excedido('a resposta com 1 aresta', Buffer.byteLength(comTeto(perguntar(1), true)));
+}
 function consultar(ctx, p) {
     // As opcoes sao conferidas antes de carregar o indice: erro de uso nao custa a leitura do grafo.
     const [a, b] = p.posicionais;
-    const profundidade = inteiro(p, 'profundidade'), limite = inteiro(p, 'limite'), s = sentido(p), t = tipos(p);
+    const profundidade = inteiro(p, 'profundidade'), limite = inteiro(p, 'limite'), s = sentido(p), t = tipos(p), teto = tetoDeBytes(p);
     const { g, cabecalho } = consultavel(ctx);
-    if (p.sub === 'vizinhos')
-        return responder(ctx, p, (0, intelligence_graph_query_1.vizinhos)(g, cabecalho, a, { profundidade, limite, sentido: s, tipos: t }));
-    if (p.sub === 'chamadores')
-        return responder(ctx, p, (0, intelligence_graph_query_1.chamadores)(g, cabecalho, a, { profundidade, limite }));
-    if (p.sub === 'importadores')
-        return responder(ctx, p, (0, intelligence_graph_query_1.importadores)(g, cabecalho, a, { profundidade, limite }));
-    return responder(ctx, p, (0, intelligence_graph_query_1.caminho)(g, cabecalho, a, b, { sentido: s, tipos: t }));
+    const perguntar = (lim) => {
+        if (p.sub === 'vizinhos')
+            return (0, intelligence_graph_query_1.vizinhos)(g, cabecalho, a, { profundidade, limite: lim, sentido: s, tipos: t });
+        if (p.sub === 'chamadores')
+            return (0, intelligence_graph_query_1.chamadores)(g, cabecalho, a, { profundidade, limite: lim });
+        if (p.sub === 'importadores')
+            return (0, intelligence_graph_query_1.importadores)(g, cabecalho, a, { profundidade, limite: lim });
+        return (0, intelligence_graph_query_1.caminho)(g, cabecalho, a, b, { sentido: s, tipos: t });
+    };
+    if (teto === undefined)
+        return responder(ctx, p, perguntar(limite));
+    ctx.escrever(respostaComTeto(perguntar, limite, teto));
+    return 0;
+}
+function contexto(ctx, p) {
+    const teto = tetoDeBytes(p);
+    if (teto !== undefined && (teto < 4096 || teto > 65536))
+        throw new intelligence_graph_query_1.ErroDeConsulta('grafo.contexto.teto-invalido', 'teto deve ser inteiro de 4096 a 65536 bytes');
+    if (!ctx.contextoDaThread)
+        throw new intelligence_graph_query_1.ErroDeConsulta('grafo.contexto.indisponivel', 'borda sem leitor da thread');
+    const lido = ctx.contextoDaThread(p.posicionais[0]);
+    const { grafo, cabecalho } = consultavel({ ...ctx, raiz: lido.raiz });
+    if (lido.head !== cabecalho.revision)
+        throw new intelligence_graph_query_1.ErroDeConsulta('grafo.contexto.revisao-mudou', 'HEAD mudou durante a leitura; repita a consulta');
+    const json = (0, intelligence_graph_contexto_1.pacoteDeContexto)(grafo, cabecalho, lido.entrada, teto);
+    if (p.bandeiras.has('json'))
+        ctx.escrever(json);
+    else {
+        const r = JSON.parse(json);
+        ctx.escrever([`Contexto ${r.thread} @ ${r.indice.revision}`,
+            `  ${r.sementes.length}/${r.total_sementes} sementes, ${r.arestas.length}/${r.total_ligacoes} ligacoes agregadas; ${r.medida.pacote_bytes} bytes JSON`,
+            `  tamanho dos arquivos no pacote (nao descoberta): ${r.medida.leitura_crua_bytes} bytes (revisao indexada); tokens: unavailable`,
+            `  diff: ${r.fontes.diff}`,
+            `  truncado: ${r.truncado}; arvore: ${r.indice.arvore}; use --json para nos e evidencias`, json].join('\n'));
+    }
+    return 0;
 }
 const sha256 = (b) => (0, node_crypto_1.createHash)('sha256').update(b).digest('hex');
 /**
@@ -392,15 +620,22 @@ function limpar(ctx, p) {
         ctx.escrever([`grafo limpar: ${r.removidos.length} removido(s), ${mb(r.bytes)}`, ...r.removidos.map((x) => `  ${x.nome} ${mb(x.bytes)}`)].join('\n'));
     return 0;
 }
-const erroEmJson = (ctx, e) => {
+/** KG5 (D4, D5): com `--teto-bytes` o erro tambem sai compacto; recusa de indice traz o estado e a correcao. */
+const erroEmJson = (ctx, e, compacto, schema = intelligence_graph_query_1.CONSULTA_SCHEMA) => {
     const [codigo, ...detalhe] = String(e.message).split('\n')[0].split(': ');
-    ctx.escrever(JSON.stringify({
-        schema: intelligence_graph_query_1.CONSULTA_SCHEMA, erro: { codigo, detalhe: detalhe.join(': ') || null, candidatos: e instanceof intelligence_graph_query_1.ErroDeConsulta ? e.candidatos : [] },
-    }, null, 2));
+    const doIndice = Object.prototype.hasOwnProperty.call(ESTADO_DO_INDICE, codigo)
+        ? { estado_do_indice: ESTADO_DO_INDICE[codigo], correcao: exports.CORRECAO_DO_INDICE } : {};
+    const r = {
+        schema,
+        erro: { codigo, detalhe: detalhe.join(': ') || null, candidatos: e instanceof intelligence_graph_query_1.ErroDeConsulta ? e.candidatos : [], ...doIndice },
+    };
+    ctx.escrever(compacto ? JSON.stringify(r) : JSON.stringify(r, null, 2));
     return 1;
 };
 /** `ork grafo <subcomando> ...`: devolve o codigo de saida; sem `--json`, o erro de uso ou tipado e lancado. */
 function executarGrafo(argv, ctx) {
+    const schema = argv[0] === 'contexto' ? intelligence_graph_contexto_1.CONTEXTO_SCHEMA : intelligence_graph_query_1.CONSULTA_SCHEMA;
+    const compacto = argv[0] === 'contexto' || argv.some((a) => a === '--teto-bytes' || a.startsWith('--teto-bytes='));
     let p;
     try {
         p = lerPedido(argv);
@@ -408,7 +643,7 @@ function executarGrafo(argv, ctx) {
     catch (e) {
         // Com `--json` no argv, tambem o erro de uso sai como objeto, como os demais.
         if (argv.includes('--json'))
-            return erroEmJson(ctx, e);
+            return erroEmJson(ctx, e, compacto, schema);
         throw e;
     }
     try {
@@ -420,11 +655,13 @@ function executarGrafo(argv, ctx) {
             return amostra(ctx, p);
         if (p.sub === 'limpar')
             return limpar(ctx, p);
+        if (p.sub === 'contexto')
+            return contexto(ctx, p);
         return consultar(ctx, p);
     }
     catch (e) {
         if (!p.bandeiras.has('json'))
             throw e;
-        return erroEmJson(ctx, e);
+        return erroEmJson(ctx, e, compacto, schema);
     }
 }

package/dist/intelligence-graph-contexto.js

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONTEXTO_FORA_DO_INDICE = exports.CONTEXTO_POR_ALVO = exports.CONTEXTO_TETO_PADRAO = exports.CONTEXTO_SCHEMA = void 0;
+exports.sementesDaThread = sementesDaThread;
+exports.pacoteDeContexto = pacoteDeContexto;
+/** KG5 fatia 3: composicao pura do contexto da thread. Sem E/S, relogio ou inferencia. */
+const node_crypto_1 = require("node:crypto");
+const intelligence_graph_contract_1 = require("./intelligence-graph-contract");
+const intelligence_graph_query_1 = require("./intelligence-graph-query");
+exports.CONTEXTO_SCHEMA = 'ork.thread-graph-context/v2';
+exports.CONTEXTO_TETO_PADRAO = 32768;
+exports.CONTEXTO_POR_ALVO = 8;
+exports.CONTEXTO_FORA_DO_INDICE = 3;
+const hash = (texto) => (0, node_crypto_1.createHash)('sha256').update(texto).digest('hex');
+/** Caminho relativo do repositorio, nunca caminho de maquina, URL ou estado privado. */
+function caminhoPublico(bruto) {
+    const p = bruto.replace(/^\.\//, '');
+    if (!p || p.startsWith('/') || p.startsWith('~') || /[:\\\u0000-\u001f\u007f]/.test(p) || p.length > 500
+        || p.split('/').some((x) => !x || x === '..' || x === '.' || x === '.git' || x === '.orkastery'))
+        return null;
+    return p;
+}
+/** GOAL/PLAN citam caminhos relativos a raiz em codigo, links ou texto; nao executam instrucoes. */
+function caminhosCitados(texto, diretorios) {
+    const r = [];
+    const semCitacoes = texto.replace(/`([^`\n]+)`|\]\(([^)\n]+)\)/g, (_m, codigo, link) => {
+        const v = codigo ?? link ?? '';
+        if (!/^(?:[a-z]+:|\/)/i.test(v) && (v.includes('/') || /\.[a-z0-9]+(?:#.*|:\d+(?::\d+)?)?$/i.test(v)
+            || /^(?:Dockerfile|Makefile|LICENSE)$/.test(v)))
+            r.push(v.replace(/#.*$/, '').replace(/:\d+(?::\d+)?$/, ''));
+        return ' ';
+    });
+    // Em prosa, exigir diretorio ou extensao de fonte conhecida evita versoes, Node.js e dominios.
+    for (const m of semCitacoes.matchAll(/(?:^|[\s(\["'])((?:[\p{L}\p{N}_@.-]+\/)+[\p{L}\p{N}_@.-]+|[\p{L}\p{N}_@-]+\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts|json|md|markdown|yaml|yml|toml|py|rs|go|c|h|css|html))(?=\.(?:\s|$)|[:#\s),;\]"']|$)/gu))
+        if (!/^Node\.js\.?$/i.test(m[1]))
+            r.push(m[1].replace(/\.$/, ''));
+    return r.filter((bruto) => {
+        const p = caminhoPublico(bruto);
+        return p !== null && !/^Node\.js$/i.test(p) && (/\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts|json|md|markdown|yaml|yml|toml|py|rs|go|c|h|css|html)$/i.test(p)
+            || /(?:^|\/)(?:Dockerfile|Makefile|LICENSE)$/.test(p)
+            || (p.includes('/') && diretorios.has(p.split('/')[0])));
+    });
+}
+function sementesDaThread(entrada, caminhosDoRepositorio = []) {
+    const diretorios = new Set(caminhosDoRepositorio.filter((p) => p.includes('/')).map((p) => p.split('/')[0]));
+    const mapa = new Map();
+    const adicionar = (bruto, origem) => {
+        const p = caminhoPublico(bruto);
+        if (!p)
+            return;
+        const origens = mapa.get(p) ?? new Set();
+        origens.add(origem);
+        mapa.set(p, origens);
+    };
+    if (entrada.diffEstado !== 'ignorado-sem-worktree')
+        for (const p of entrada.diff)
+            adicionar(p, 'diff');
+    for (const tipo of ['goal', 'plan'])
+        for (const p of caminhosCitados(entrada[tipo] ?? '', diretorios))
+            adicionar(p, tipo);
+    for (const c of entrada.claims)
+        adicionar(c.arquivo, `claim:${c.id}`);
+    return [...mapa].sort(([a], [b]) => (0, intelligence_graph_contract_1.compararUtf8)(a, b))
+        .map(([arquivo, origens]) => ({ arquivo, origens: [...origens].sort(intelligence_graph_contract_1.compararUtf8) }));
+}
+/** O grafo recebido ja deve estar filtrado pela concessao de quem consulta. */
+function pacoteDeContexto(grafo, indice, entrada, tetoBytes = exports.CONTEXTO_TETO_PADRAO) {
+    if (!Number.isInteger(tetoBytes) || tetoBytes < 4096 || tetoBytes > 65536)
+        throw new intelligence_graph_query_1.ErroDeConsulta('grafo.contexto.teto-invalido', 'teto deve ser inteiro de 4096 a 65536 bytes');
+    const porId = new Map(grafo.nodes.map((n) => [n.node_id, n]));
+    const arquivos = new Set(grafo.nodes.filter((n) => n.kind === 'file').map((n) => n.locator.path));
+    const sementes = sementesDaThread(entrada, [...arquivos]).map((s) => ({ ...s, estado: arquivos.has(s.arquivo) ? 'indexado' : 'fora-do-indice' }));
+    const indexadas = sementes.filter((s) => s.estado === 'indexado'), ausentes = sementes.filter((s) => s.estado !== 'indexado');
+    const alvos = new Set(indexadas.map((s) => s.arquivo));
+    const diff = entrada.diffEstado === 'ignorado-sem-worktree' ? [] : [...new Set(entrada.diff)].sort(intelligence_graph_contract_1.compararUtf8);
+    // Distancia em arquivos, em ambos os sentidos, sem depender da ordem das arestas.
+    const adj = new Map();
+    for (const a of grafo.edges) {
+        const de = porId.get(a.from).locator.path, para = porId.get(a.to).locator.path;
+        if (de === para)
+            continue;
+        if (!adj.has(de))
+            adj.set(de, new Set());
+        if (!adj.has(para))
+            adj.set(para, new Set());
+        adj.get(de).add(para);
+        adj.get(para).add(de);
+    }
+    const dist = new Map(diff.filter((p) => arquivos.has(p)).map((p) => [p, 0]));
+    const fila = [...dist.keys()];
+    for (let i = 0; i < fila.length; i++)
+        for (const p of adj.get(fila[i]) ?? []) {
+            if (!dist.has(p)) {
+                dist.set(p, dist.get(fila[i]) + 1);
+                fila.push(p);
+            }
+        }
+    const extratores = [...indice.extratores].sort((a, b) => (0, intelligence_graph_contract_1.compararUtf8)((0, intelligence_graph_contract_1.canonico)(a), (0, intelligence_graph_contract_1.canonico)(b)));
+    const extratorIds = new Map(extratores.map((e, i) => [(0, intelligence_graph_contract_1.canonico)(e), i]));
+    const grupos = new Map();
+    let totalArestas = 0, estruturais = 0, evidenciasAuxiliares = 0;
+    for (const a of grafo.edges) {
+        const de = porId.get(a.from), para = porId.get(a.to);
+        if (!alvos.has(de.locator.path) && !alvos.has(para.locator.path))
+            continue;
+        totalArestas++;
+        if ((a.kind === 'declares' || a.kind === 'contains') && de.locator.path === para.locator.path && alvos.has(de.locator.path)) {
+            estruturais++;
+            continue;
+        }
+        const proprias = a.evidence.filter((e) => e.path === de.locator.path);
+        evidenciasAuxiliares += a.evidence.length - proprias.length;
+        // Sem evidencia no arquivo de origem, a aresta fica em omitidos.arestas.
+        if (!proprias.length)
+            continue;
+        const origem = `file ${de.locator.path}`, destino = (0, intelligence_graph_query_1.rotuloDoNo)(para);
+        const chave = (0, intelligence_graph_contract_1.canonico)([a.kind, destino, de.locator.path]);
+        const grupo = grupos.get(chave) ?? { kind: a.kind, origem, destino, alvo: para.node_id, quantidade: 0,
+            evidencias: new Map(), entreArquivos: de.locator.path !== para.locator.path,
+            distancia: Math.min(dist.get(de.locator.path) ?? Infinity, dist.get(para.locator.path) ?? Infinity) };
+        grupo.quantidade++;
+        for (const e of proprias) {
+            const x = extratorIds.get((0, intelligence_graph_contract_1.canonico)({ extractor_id: e.extractor_id, extractor_version: e.extractor_version }));
+            if (x === undefined)
+                throw new intelligence_graph_query_1.ErroDeConsulta('grafo.contexto.extrator-ausente', 'extrator da evidencia ausente no cabecalho');
+            const s = e.span;
+            const tupla = [x, e.extraction_method,
+                s.type === 'text' ? [s.line_start, s.line_end] : ['pdf', s.page, s.extracted_text_hash], [s.byte_start, s.byte_end]];
+            grupo.evidencias.set((0, intelligence_graph_contract_1.canonico)(tupla), tupla);
+        }
+        grupos.set(chave, grupo);
+    }
+    // Entre arquivos > perto do diff > tipo > rotulos; empates independem da ordem do indice.
+    const ordenados = [...grupos.values()].sort((a, b) => Number(b.entreArquivos) - Number(a.entreArquivos)
+        || (a.distancia === b.distancia ? 0 : a.distancia < b.distancia ? -1 : 1)
+        || (0, intelligence_graph_contract_1.compararUtf8)(a.kind, b.kind) || (0, intelligence_graph_contract_1.compararUtf8)(a.destino, b.destino) || (0, intelligence_graph_contract_1.compararUtf8)(a.origem, b.origem));
+    // Dentro da mesma prioridade, intercalar tipos impede calls de expulsar imports/references.
+    const rodadas = new Map();
+    const justos = ordenados.map((g) => {
+        const chave = JSON.stringify([g.alvo, g.entreArquivos, g.distancia, g.kind]);
+        const rodada = rodadas.get(chave) ?? 0;
+        rodadas.set(chave, rodada + 1);
+        return { g, rodada };
+    }).sort((a, b) => Number(b.g.entreArquivos) - Number(a.g.entreArquivos)
+        || (a.g.distancia === b.g.distancia ? 0 : a.g.distancia < b.g.distancia ? -1 : 1)
+        || a.rodada - b.rodada || (0, intelligence_graph_contract_1.compararUtf8)(a.g.kind, b.g.kind)
+        || (0, intelligence_graph_contract_1.compararUtf8)(a.g.destino, b.g.destino) || (0, intelligence_graph_contract_1.compararUtf8)(a.g.origem, b.g.origem)).map(({ g }) => g);
+    const normalizada = { ...entrada, diff, diffEstado: entrada.diffEstado ?? 'coletado-na-worktree',
+        claims: [...entrada.claims].sort((a, b) => (0, intelligence_graph_contract_1.compararUtf8)((0, intelligence_graph_contract_1.canonico)(a), (0, intelligence_graph_contract_1.canonico)(b))) };
+    const fixo = { schema: exports.CONTEXTO_SCHEMA, thread: entrada.thread, base: entrada.base, entrada_sha256: hash((0, intelligence_graph_contract_1.canonico)(normalizada)),
+        indice: { ...indice, extratores },
+        fontes: { goal: entrada.goal === null ? 'ausente' : hash(entrada.goal), plan: entrada.plan === null ? 'ausente' : hash(entrada.plan),
+            diff: normalizada.diffEstado },
+        consulta: { profundidade: 1, sentido: 'ambos', por_alvo: exports.CONTEXTO_POR_ALVO, fora_do_indice: exports.CONTEXTO_FORA_DO_INDICE },
+        total_sementes: sementes.length, sementes_fora_do_indice: ausentes.length, total_arestas: totalArestas,
+        total_ligacoes: ordenados.length, resumidas: { estruturais }, parcial: intelligence_graph_query_1.AVISO_DE_PARCIALIDADE };
+    const selecionadas = [], ligacoes = [];
+    const montar = () => {
+        const caminhos = new Set(selecionadas.filter((s) => s.estado === 'indexado').map((s) => s.arquivo));
+        const rotulos = new Set([...caminhos].map((p) => `file ${p}`));
+        for (const a of ligacoes) {
+            rotulos.add(a.origem);
+            rotulos.add(a.destino);
+            caminhos.add(porId.get(a.alvo).locator.path);
+            caminhos.add(a.origem.slice(5));
+        }
+        const refs = new Map([...rotulos].sort(intelligence_graph_contract_1.compararUtf8).map((r, i) => [r, `n${i + 1}`]));
+        const fontes = grafo.snapshot.source_manifest.filter((m) => caminhos.has(m.path)).sort((a, b) => (0, intelligence_graph_contract_1.compararUtf8)(a.path, b.path));
+        const omitidos = { sementes: sementes.length - selecionadas.length, ligacoes: ordenados.length - ligacoes.length,
+            arestas: totalArestas - estruturais - ligacoes.reduce((s, a) => s + a.quantidade, 0), evidencias_auxiliares: evidenciasAuxiliares };
+        const cortado = omitidos.sementes > 0 || omitidos.ligacoes > 0 || omitidos.arestas > 0 || evidenciasAuxiliares > 0;
+        const r = { ...fixo, sementes: selecionadas, nos: Object.fromEntries([...refs].map(([r, ref]) => [ref, r])),
+            arestas: ligacoes.map((a) => ({ kind: a.kind, from: refs.get(a.origem), to: refs.get(a.destino), quantidade: a.quantidade,
+                evidencias: [...a.evidencias].sort(([a], [b]) => (0, intelligence_graph_contract_1.compararUtf8)(a, b)).map(([, e]) => e) })),
+            truncado: cortado, omitidos, teto: { bytes: tetoBytes, cortado },
+            medida: { pacote_bytes: 0, leitura_crua_bytes: fontes.reduce((s, f) => s + f.size_bytes, 0),
+                arquivos: fontes.map((f) => ({ path: f.path, bytes: f.size_bytes })),
+                origem: 'source_manifest; tamanho dos arquivos, nao custo de descoberta', tokens: 'unavailable' } };
+        let texto = (0, intelligence_graph_contract_1.canonico)(r);
+        while (r.medida.pacote_bytes !== Buffer.byteLength(texto)) {
+            r.medida.pacote_bytes = Buffer.byteLength(texto);
+            texto = (0, intelligence_graph_contract_1.canonico)(r);
+        }
+        return texto;
+    };
+    let melhor = montar();
+    if (Buffer.byteLength(melhor) > tetoBytes)
+        throw new intelligence_graph_query_1.ErroDeConsulta('grafo.contexto.teto-excedido', 'cabecalho nao cabe no teto');
+    const tentarSemente = (s) => {
+        selecionadas.push(s);
+        const texto = montar();
+        if (Buffer.byteLength(texto) <= tetoBytes)
+            melhor = texto;
+        else
+            selecionadas.pop();
+    };
+    for (const s of indexadas)
+        tentarSemente(s);
+    const porAlvo = new Map();
+    for (const a of justos) {
+        if ((porAlvo.get(a.alvo) ?? 0) >= exports.CONTEXTO_POR_ALVO)
+            continue;
+        ligacoes.push(a);
+        const texto = montar();
+        if (Buffer.byteLength(texto) <= tetoBytes) {
+            melhor = texto;
+            porAlvo.set(a.alvo, (porAlvo.get(a.alvo) ?? 0) + 1);
+        }
+        else
+            ligacoes.pop(); // Um hub grande nao impede uma ligacao menor e relevante de entrar.
+    }
+    for (const s of ausentes.slice(0, exports.CONTEXTO_FORA_DO_INDICE))
+        tentarSemente(s);
+    return melhor;
+}