@orkastery/cli 0.4.3 → 0.5.0

package/dist/intelligence-graph-index.js

@@ -0,0 +1,512 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.versoesDoParser = exports.EXCLUSOES_DA_ARVORE = exports.MODULOS_DO_EXTRATOR = exports.PRAZO_DE_SOBRA_MS = exports.NOME_DE_INDICE = exports.INDICE_SCHEMA = void 0;
+exports.impressaoDoExtrator = impressaoDoExtrator;
+exports.perfilDoIndice = perfilDoIndice;
+exports.chaveDoIndice = chaveDoIndice;
+exports.concessaoLocal = concessaoLocal;
+exports.pastaDoGrafo = pastaDoGrafo;
+exports.lerIndice = lerIndice;
+exports.construirIndice = construirIndice;
+exports.indiceDoHead = indiceDoHead;
+exports.estadoDosIndices = estadoDosIndices;
+exports.limparIndices = limparIndices;
+/**
+ * RM-031 KG3 (D2 a D4, D6): indice persistente e local do grafo de codigo.
+ *
+ * O indice e derivado do grafo do KG2 e chaveado pela revisao da arvore limpa: mora no estado
+ * canonico do projeto, fora do git, uma pasta por chave:
+ *
+ *   <raiz canonica>/.orkastery/grafo/idx-<sha256>/{indice.json, grafo.json, relatorio.json}
+ *
+ * Pastas 0700 e arquivos 0600, do dono do processo, sem link simbolico nem segundo link fisico. A
+ * chave deriva da revisao, do repositorio, do tenant, da ACL, das versoes dos analisadores, do fecho
+ * de pacotes deles e da impressao do codigo compilado do extrator e do indice: mesma chave, mesmo
+ * conteudo, byte a byte, sem horario. Arquivo rastreado que a leitura nao alcanca (sparse checkout,
+ * `skip-worktree`) recusa a construcao: o grafo precisa ser o da revisao inteira.
+ * A construcao valida o grafo, confere cada fonte e cada evidencia contra os bytes lidos e so entao
+ * publica, por pasta temporaria e `rename`; a leitura confere tamanho e digest dos bytes.
+ *
+ * O indice nao e autoridade de fato: e projecao descartavel do repositorio. Nada nele concede acesso.
+ */
+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_extract_1 = require("./intelligence-graph-extract");
+const intelligence_graph_parsers_1 = require("./intelligence-graph-parsers");
+const intelligence_graph_repo_1 = require("./intelligence-graph-repo");
+exports.INDICE_SCHEMA = 'ork.code-graph-index/v0';
+exports.NOME_DE_INDICE = /^idx-[a-f0-9]{64}$/;
+const ARQUIVOS = { manifesto: 'indice.json', grafo: 'grafo.json', relatorio: 'relatorio.json' };
+/** Temporario e lixo de construcao interrompida so saem no `limpar` depois deste prazo. */
+exports.PRAZO_DE_SOBRA_MS = 60 * 60 * 1000;
+/** D3: os modulos compilados da extracao e do indice. Codigo corrigido sem troca de versao muda a chave. */
+exports.MODULOS_DO_EXTRATOR = [
+    'intelligence-graph-contract', 'intelligence-graph-extract', 'intelligence-graph-extract-ts', 'intelligence-graph-extract-md',
+    'intelligence-graph-repo', 'intelligence-graph-parsers', 'intelligence-graph-index', 'yaml',
+];
+/**
+ * CHECK rodada 1 (B1): exclusoes do KG2 que dependem da arvore, nao da revisao. Com o status limpo,
+ * elas vem de sparse checkout ou `skip-worktree`, e o grafo seria outro na mesma revisao.
+ */
+exports.EXCLUSOES_DA_ARVORE = new Set(['ausente-na-arvore', 'nao-e-arquivo', 'fora-do-repositorio']);
+function falha(codigo, detalhe) {
+    throw new Error(detalhe ? `${codigo}: ${detalhe}` : codigo);
+}
+const sha256 = (b) => (0, node_crypto_1.createHash)('sha256').update(b).digest('hex');
+const uid = () => (typeof process.getuid === 'function' ? process.getuid() : null);
+/** As versoes do `Parser` carregado, no formato que `versoesDosAnalisadores` le sem carregar. */
+const versoesDoParser = (p) => ({ typescript: p.ts.version, javascript: p.javascript.versao, markdown: p.markdown.versao, unicode: p.unicode });
+exports.versoesDoParser = versoesDoParser;
+/** D3: SHA-256 dos bytes compilados dos modulos da extracao, na ordem fixa; `dir` so muda em teste. */
+function impressaoDoExtrator(dir = __dirname) {
+    const h = (0, node_crypto_1.createHash)('sha256');
+    for (const m of exports.MODULOS_DO_EXTRATOR) {
+        const bytes = fs.readFileSync(path.join(dir, `${m}.js`));
+        h.update(`${m}\u0000${bytes.length}\u0000`).update(bytes);
+    }
+    return h.digest('hex');
+}
+function perfilDoIndice(raiz, analisadores = (0, intelligence_graph_parsers_1.versoesDosAnalisadores)(), leitura = {}) {
+    const id = (0, intelligence_graph_repo_1.identidadeDaLeitura)(raiz, leitura);
+    return {
+        ...id, acl_refs: [...new Set(id.acl_refs)].sort(intelligence_graph_contract_1.compararUtf8), analisadores, pacotes: (0, intelligence_graph_parsers_1.pacotesDosAnalisadores)(), codigo: impressaoDoExtrator(),
+    };
+}
+/** A leitura do contexto: o repositorio do manifesto do CLI, se veio, sob as opcoes pedidas. */
+const leituraDo = (ctx, leitura = {}) => (ctx.repositorio && leitura.repository_id === undefined ? { ...leitura, repository_id: ctx.repositorio } : leitura);
+/** D3: a chave particiona por revisao, repositorio, tenant, ACL, analisadores e codigo do extrator. */
+function chaveDoIndice(revision, perfil) {
+    return `idx-${(0, intelligence_graph_contract_1.sha256DoCanonico)({ schema: exports.INDICE_SCHEMA, revision, ...perfil })}`;
+}
+/**
+ * D6: a avaliacao local. Quem roda o CLI e le a raiz do repositorio recebe a leitura dele, no
+ * tenant local; nada mais. Sem leitura, a recusa e explicita, sem cair para outro escopo.
+ */
+function concessaoLocal(raiz, perfil) {
+    try {
+        fs.accessSync(raiz, fs.constants.R_OK | fs.constants.X_OK);
+    }
+    catch {
+        falha('grafo.acesso.negado', 'quem roda o CLI nao le a raiz do repositorio');
+    }
+    return { tenant_id: intelligence_graph_repo_1.TENANT_PADRAO, acl_refs: [`repo:${perfil.repository_id}:leitura`] };
+}
+/** Pasta do estado: real, do dono e 0700; `criar` ajusta a que o proprio processo cria. */
+function pastaPrivada(p, criar) {
+    if (criar) {
+        try {
+            fs.mkdirSync(p, { mode: 0o700 });
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+        }
+    }
+    const st = fs.lstatSync(p, { throwIfNoEntry: false });
+    if (!st)
+        falha('grafo.indice.ausente');
+    if (st.isSymbolicLink() || !st.isDirectory())
+        falha('grafo.indice.permissao-invalida', `${path.basename(p)} nao e pasta real`);
+    const dono = uid();
+    if (dono !== null && st.uid !== dono)
+        falha('grafo.indice.permissao-invalida', `${path.basename(p)} de outro dono`);
+    if ((st.mode & 0o777) !== 0o700) {
+        if (!criar)
+            falha('grafo.indice.permissao-invalida', `${path.basename(p)} com modo ${(st.mode & 0o777).toString(8)}`);
+        fs.chmodSync(p, 0o700);
+    }
+}
+/** `<estado>/.orkastery/grafo`, real e privada. So a construcao cria. */
+function pastaDoGrafo(ctx, criar) {
+    const estado = path.join(ctx.estado, '.orkastery');
+    if (criar)
+        fs.mkdirSync(estado, { recursive: true });
+    const st = fs.lstatSync(estado, { throwIfNoEntry: false });
+    if (!st)
+        falha('grafo.indice.ausente');
+    if (st.isSymbolicLink() || !st.isDirectory())
+        falha('grafo.indice.permissao-invalida', '.orkastery nao e pasta real');
+    const dir = path.join(estado, 'grafo');
+    pastaPrivada(dir, criar);
+    return dir;
+}
+/** Le arquivo do indice pelo descritor aberto sem seguir link: regular, do dono, 0600 e com um link so. */
+function lerPrivado(arquivo) {
+    let fd;
+    try {
+        fd = fs.openSync(arquivo, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    }
+    catch (e) {
+        const codigo = e.code;
+        if (codigo === 'ENOENT')
+            falha('grafo.indice.corrompido', `${path.basename(arquivo)} ausente`);
+        falha('grafo.indice.permissao-invalida', `${path.basename(arquivo)} (${codigo ?? 'erro'})`);
+    }
+    try {
+        const st = fs.fstatSync(fd);
+        const dono = uid();
+        if (!st.isFile() || st.nlink !== 1 || (dono !== null && st.uid !== dono) || (st.mode & 0o777) !== 0o600) {
+            falha('grafo.indice.permissao-invalida', path.basename(arquivo));
+        }
+        return fs.readFileSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function gravarPrivado(arquivo, texto) {
+    const fd = fs.openSync(arquivo, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+    try {
+        fs.fchmodSync(fd, 0o600);
+        fs.writeFileSync(fd, texto, 'utf8');
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function sincronizarPasta(dir) {
+    const fd = fs.openSync(dir, 'r');
+    try {
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+const HEX64 = /^[a-f0-9]{64}$/;
+function manifestoValido(m, chave) {
+    const o = m;
+    const inteiro = (n) => Number.isSafeInteger(n) && n >= 0;
+    if (!o || typeof o !== 'object' || o.schema !== exports.INDICE_SCHEMA || o.chave !== chave || o.graph_schema !== intelligence_graph_contract_1.GRAFO_SCHEMA
+        || typeof o.revision !== 'string' || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(o.revision)
+        || !HEX64.test(o.graph_digest) || !HEX64.test(o.report_digest) || !inteiro(o.graph_bytes) || !inteiro(o.report_bytes)
+        || typeof o.snapshot_id !== 'string' || typeof o.repository_id !== 'string' || typeof o.tenant_id !== 'string'
+        || !Array.isArray(o.acl_refs) || !o.analisadores || !Array.isArray(o.pacotes) || typeof o.codigo !== 'string') {
+        falha('grafo.indice.corrompido', 'indice.json');
+    }
+    return o;
+}
+/**
+ * Le o indice da chave e confere a integridade: permissao de pasta e arquivo, manifesto, tamanho e
+ * digest dos bytes do grafo e do relatorio, e o envelope do grafo contra o manifesto. Nao roda
+ * `validarGrafo` (D4): a construcao ja validou, e o digest prova que os bytes sao aqueles.
+ */
+function lerIndice(ctx, chave, opcoes = {}) {
+    if (!exports.NOME_DE_INDICE.test(chave))
+        falha('grafo.indice.chave-invalida');
+    const dir = path.join(pastaDoGrafo(ctx, false), chave);
+    pastaPrivada(dir, false);
+    let manifesto;
+    try {
+        manifesto = manifestoValido(JSON.parse(lerPrivado(path.join(dir, ARQUIVOS.manifesto)).toString('utf8')), chave);
+    }
+    catch (e) {
+        if (e instanceof SyntaxError)
+            falha('grafo.indice.corrompido', 'indice.json');
+        throw e;
+    }
+    const conferido = (nome, bytes, digest) => {
+        const b = lerPrivado(path.join(dir, nome));
+        if (b.length !== bytes || sha256(b) !== digest)
+            falha('grafo.indice.corrompido', `${nome} nao bate com o digest`);
+        return b;
+    };
+    const bytesDoGrafo = conferido(ARQUIVOS.grafo, manifesto.graph_bytes, manifesto.graph_digest);
+    const bytesDoRelatorio = conferido(ARQUIVOS.relatorio, manifesto.report_bytes, manifesto.report_digest);
+    let grafo = null;
+    if (opcoes.grafo !== false) {
+        grafo = JSON.parse(bytesDoGrafo.toString('utf8'));
+        const s = grafo.snapshot;
+        if (grafo.schema !== intelligence_graph_contract_1.GRAFO_SCHEMA || grafo.tenant_id !== manifesto.tenant_id || grafo.repository_id !== manifesto.repository_id
+            || !s || s.snapshot_id !== manifesto.snapshot_id || s.revision !== manifesto.revision) {
+            falha('grafo.indice.corrompido', 'grafo.json fora do manifesto');
+        }
+    }
+    const relatorio = opcoes.relatorio ? JSON.parse(bytesDoRelatorio.toString('utf8')) : null;
+    return { dir, manifesto, grafo, relatorio };
+}
+/** Embaralhamento reproduzivel (LCG): a permutacao da verificacao nao depende de acaso. */
+function embaralhar(itens, semente) {
+    const r = [...itens];
+    let s = semente >>> 0;
+    for (let i = r.length - 1; i > 0; i--) {
+        s = (Math.imul(s, 1664525) + 1013904223) >>> 0;
+        const j = s % (i + 1);
+        [r[i], r[j]] = [r[j], r[i]];
+    }
+    return r;
+}
+function mesmoConteudo(dir, conteudos) {
+    try {
+        return Object.entries(conteudos).every(([nome, texto]) => lerPrivado(path.join(dir, nome)).equals(Buffer.from(texto, 'utf8')))
+            && fs.readdirSync(dir).length === Object.keys(conteudos).length;
+    }
+    catch {
+        return false;
+    }
+}
+function removerPasta(grafoDir, nome) {
+    const alvo = path.join(grafoDir, nome);
+    const st = fs.lstatSync(alvo, { throwIfNoEntry: false });
+    if (!st)
+        return;
+    if (st.isSymbolicLink() || !st.isDirectory()) {
+        fs.unlinkSync(alvo);
+        return;
+    }
+    // Renomeia antes de apagar: quem le nunca ve a pasta da chave pela metade.
+    const lixo = nome.startsWith('.lixo-') ? alvo : path.join(grafoDir, `.lixo-${(0, node_crypto_1.randomUUID)()}`);
+    if (lixo !== alvo)
+        fs.renameSync(alvo, lixo);
+    fs.rmSync(lixo, { recursive: true, force: true });
+}
+/**
+ * Constroi o indice do HEAD limpo, ou confirma o que ja existe. `--forcar` extrai de novo e so
+ * troca os arquivos se o conteudo mudou; `--verificar` extrai de novo, prova o determinismo com a
+ * ordem de leitura trocada e reprova se o guardado integro difere; indice que nao passa na leitura
+ * e substituido.
+ */
+function construirIndice(ctx, opcoes = {}) {
+    const inicio = process.hrtime.bigint();
+    const ms = () => Number((process.hrtime.bigint() - inicio) / 1000000n);
+    const arvore = (0, intelligence_graph_repo_1.revisaoDaArvore)(ctx.raiz);
+    if (arvore.motivo !== null || arvore.head === null)
+        falha('grafo.indice.arvore-nao-limpa', arvore.motivo ?? 'sem-commit');
+    const parser = opcoes.parser ?? (0, intelligence_graph_parsers_1.carregarAnalisadores)();
+    const leitura = leituraDo(ctx, opcoes.leitura);
+    const perfil = perfilDoIndice(arvore.raiz, (0, exports.versoesDoParser)(parser), leitura);
+    const chave = chaveDoIndice(arvore.head, perfil);
+    const grafoDir = pastaDoGrafo(ctx, true);
+    const final = path.join(grafoDir, chave);
+    let motivo = null;
+    const existia = !!fs.lstatSync(final, { throwIfNoEntry: false });
+    if (existia) {
+        try {
+            const atual = lerIndice(ctx, chave, { grafo: false });
+            // `--verificar` nunca confia no guardado: extrai de novo e compara, como o `--forcar`.
+            if (!opcoes.forcar && !opcoes.verificar)
+                return { estado: 'existente', motivo: null, chave, dir: final, manifesto: atual.manifesto, determinismo: null, ms: ms() };
+        }
+        catch (e) {
+            motivo = e.message;
+        }
+    }
+    const entrada = (0, intelligence_graph_repo_1.lerRepositorio)(arvore.raiz, leitura);
+    if (entrada.revision !== arvore.head)
+        falha('grafo.indice.arvore-nao-limpa', entrada.revision_unavailable_reason ?? 'revisao-mudou');
+    const fora = (entrada.excluidas ?? []).filter((e) => exports.EXCLUSOES_DA_ARVORE.has(e.motivo)).sort((a, b) => (0, intelligence_graph_contract_1.compararUtf8)(a.path, b.path));
+    if (fora.length) {
+        falha('grafo.indice.arvore-nao-limpa', `rastreado fora da leitura (${fora[0].motivo}: ${fora[0].path}${fora.length > 1 ? ` e mais ${fora.length - 1}` : ''})`);
+    }
+    const r = (0, intelligence_graph_extract_1.extrairGrafo)(entrada, parser);
+    const bytesDe = new Map(entrada.fontes.map((f) => [f.path, f.bytes]));
+    const fornecidas = new Map(r.grafo.snapshot.source_manifest.map((m) => {
+        const b = bytesDe.get(m.path);
+        return [m.path, { tipo: (0, intelligence_graph_extract_1.decodificarUtf8)(b) === null ? 'binario' : 'texto', bytes: b }];
+    }));
+    const conferencia = (0, intelligence_graph_contract_1.conferirFontes)(r.grafo, fornecidas);
+    if (conferencia.estado !== 'verificada' || conferencia.evidenciasIndisponiveis > 0)
+        falha('grafo.indice.fontes-nao-conferidas');
+    let determinismo = null;
+    if (opcoes.verificar) {
+        const relatorio = (0, intelligence_graph_contract_1.sha256DoCanonico)(r.relatorio);
+        determinismo = [['ordem invertida', [...entrada.fontes].reverse()], ['ordem embaralhada', embaralhar(entrada.fontes, 2026)]]
+            .map(([ordem, fontes]) => {
+            const outra = (0, intelligence_graph_extract_1.extrairGrafo)({ ...entrada, fontes }, parser);
+            const doOutro = (0, intelligence_graph_contract_1.sha256DoCanonico)(outra.relatorio);
+            return { ordem, digest: outra.digest, relatorio: doOutro, igual: outra.digest === r.digest && doOutro === relatorio };
+        });
+        const diferente = determinismo.find((d) => !d.igual);
+        if (diferente)
+            falha('grafo.indice.nao-deterministico', diferente.ordem);
+    }
+    const textoDoGrafo = (0, intelligence_graph_contract_1.canonico)(r.grafo), textoDoRelatorio = (0, intelligence_graph_contract_1.canonico)(r.relatorio);
+    if (sha256(textoDoGrafo) !== r.digest)
+        falha('grafo.indice.digest-divergente');
+    const manifesto = {
+        schema: exports.INDICE_SCHEMA, chave, revision: arvore.head, ...perfil, graph_schema: intelligence_graph_contract_1.GRAFO_SCHEMA, snapshot_id: r.grafo.snapshot.snapshot_id,
+        graph_digest: r.digest, graph_bytes: Buffer.byteLength(textoDoGrafo, 'utf8'),
+        report_digest: sha256(textoDoRelatorio), report_bytes: Buffer.byteLength(textoDoRelatorio, 'utf8'),
+        contagens: r.relatorio.contagens,
+        conferencia: { fontes: conferencia.fontesVerificadas.length, evidencias: conferencia.evidenciasVerificadas },
+    };
+    const conteudos = {
+        [ARQUIVOS.manifesto]: (0, intelligence_graph_contract_1.canonico)(manifesto), [ARQUIVOS.grafo]: textoDoGrafo, [ARQUIVOS.relatorio]: textoDoRelatorio,
+    };
+    const tmp = path.join(grafoDir, `.tmp-${(0, node_crypto_1.randomUUID)()}`);
+    pastaPrivada(tmp, true);
+    try {
+        for (const [nome, texto] of Object.entries(conteudos))
+            gravarPrivado(path.join(tmp, nome), texto);
+        sincronizarPasta(tmp);
+        opcoes.antesDePublicar?.();
+        const resultado = (estado) => ({ estado, motivo, chave, dir: final, manifesto, determinismo, ms: ms() });
+        if (!existia && fs.lstatSync(final, { throwIfNoEntry: false })) {
+            // Corrida: outra construcao publicou a mesma chave durante esta. Vale a dela, se estiver integra.
+            lerIndice(ctx, chave, { grafo: false });
+            return resultado('existente');
+        }
+        if (existia && fs.lstatSync(final, { throwIfNoEntry: false })) {
+            if (motivo === null && mesmoConteudo(final, conteudos))
+                return resultado('reconstruido-identico');
+            // Mesma chave e conteudo integro diferente: a extracao nao se repetiu. A verificacao reprova; o forcar troca.
+            if (motivo === null && opcoes.verificar)
+                falha('grafo.indice.nao-deterministico', 'o indice guardado difere da extracao nova');
+            if (motivo === null)
+                motivo = 'conteudo diferente na mesma chave';
+            removerPasta(grafoDir, chave);
+            fs.renameSync(tmp, final);
+            sincronizarPasta(grafoDir);
+            return resultado('substituido');
+        }
+        try {
+            fs.renameSync(tmp, final);
+        }
+        catch (e) {
+            const codigo = e.code;
+            if (codigo !== 'ENOTEMPTY' && codigo !== 'EEXIST')
+                throw e;
+            lerIndice(ctx, chave, { grafo: false });
+            return resultado('existente');
+        }
+        sincronizarPasta(grafoDir);
+        return resultado('criado');
+    }
+    finally {
+        if (fs.lstatSync(tmp, { throwIfNoEntry: false }))
+            fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+/** O indice do HEAD com o extrator desta instalacao, e a arvore como esta agora. */
+function indiceDoHead(ctx, opcoes = {}) {
+    const arvore = (0, intelligence_graph_repo_1.revisaoDaArvore)(ctx.raiz);
+    if (arvore.head === null)
+        falha('grafo.indice.arvore-nao-limpa', 'sem-commit');
+    const perfil = perfilDoIndice(arvore.raiz, undefined, leituraDo(ctx));
+    const chave = chaveDoIndice(arvore.head, perfil);
+    try {
+        return { arvore, perfil, chave, indice: lerIndice(ctx, chave, opcoes) };
+    }
+    catch (e) {
+        if (e.message === 'grafo.indice.ausente')
+            falha('grafo.indice.ausente', `sem indice do HEAD ${arvore.head.slice(0, 12)}; rode ork grafo indexar`);
+        throw e;
+    }
+}
+function bytesDaPasta(dir) {
+    let total = 0;
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+        const p = path.join(dir, e.name);
+        const st = fs.lstatSync(p);
+        total += st.isDirectory() ? bytesDaPasta(p) : st.size;
+    }
+    return total;
+}
+/** Os indices guardados, com a integridade de cada um, e as sobras de construcao interrompida. */
+function estadoDosIndices(ctx) {
+    let dir;
+    try {
+        dir = pastaDoGrafo(ctx, false);
+    }
+    catch (e) {
+        if (e.message === 'grafo.indice.ausente')
+            return { dir: null, indices: [], sobras: [], bytes: 0 };
+        throw e;
+    }
+    const indices = [], sobras = [];
+    let bytes = 0;
+    for (const nome of fs.readdirSync(dir).sort(intelligence_graph_contract_1.compararUtf8)) {
+        // Uma construcao concorrente pode renomear o `.tmp-` entre a listagem e o `lstat`: some da lista.
+        const p = path.join(dir, nome), st = fs.lstatSync(p, { throwIfNoEntry: false });
+        if (!st)
+            continue;
+        let tamanho;
+        try {
+            tamanho = st.isDirectory() && !st.isSymbolicLink() ? bytesDaPasta(p) : st.size;
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                continue;
+            throw e;
+        }
+        bytes += tamanho;
+        if (!exports.NOME_DE_INDICE.test(nome)) {
+            sobras.push(nome);
+            continue;
+        }
+        try {
+            const { manifesto } = lerIndice(ctx, nome, { grafo: false });
+            indices.push({ chave: nome, bytes: tamanho, revision: manifesto.revision, repository_id: manifesto.repository_id, snapshot_id: manifesto.snapshot_id, problema: null });
+        }
+        catch (e) {
+            indices.push({ chave: nome, bytes: tamanho, revision: null, repository_id: null, snapshot_id: null, problema: e.message });
+        }
+    }
+    return { dir, indices, sobras, bytes };
+}
+/**
+ * Apaga os indices fora de `manter` e cuja revisao nao esta em `manterRevisoes` (ou todos, com
+ * `tudo`), e as sobras `.tmp-` e `.lixo-` com mais de uma hora. Nome que nao e do indice nunca e
+ * apagado.
+ */
+function limparIndices(ctx, opcoes = {}) {
+    const estado = estadoDosIndices(ctx);
+    if (!estado.dir)
+        return { removidos: [], bytes: 0 };
+    const dir = estado.dir, agora = opcoes.agora ?? Date.now(), manter = new Set(opcoes.manter ?? []);
+    const revisoes = new Set(opcoes.manterRevisoes ?? []);
+    const removidos = [];
+    for (const i of estado.indices) {
+        if (!opcoes.tudo && (manter.has(i.chave) || (i.revision !== null && revisoes.has(i.revision))))
+            continue;
+        removerPasta(dir, i.chave);
+        removidos.push({ nome: i.chave, bytes: i.bytes });
+    }
+    for (const nome of estado.sobras) {
+        if (!/^\.(tmp|lixo)-[0-9a-f-]{36}$/.test(nome))
+            continue;
+        const p = path.join(dir, nome), st = fs.lstatSync(p, { throwIfNoEntry: false });
+        if (!st || agora - st.mtimeMs < exports.PRAZO_DE_SOBRA_MS)
+            continue;
+        const tamanho = st.isDirectory() && !st.isSymbolicLink() ? bytesDaPasta(p) : st.size;
+        removerPasta(dir, nome);
+        removidos.push({ nome, bytes: tamanho });
+    }
+    return { removidos, bytes: removidos.reduce((n, r) => n + r.bytes, 0) };
+}