@orkastery/cli 0.5.0 → 0.5.3

package/dist/intelligence-graph-extract.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.textoAceito = exports.LACUNAS_SO_CONTAGEM = exports.EXTENSOES_MD = exports.EXTENSOES_TS = exports.CONFIG_SCHEMA = exports.RELATORIO_SCHEMA = exports.VERSAO_KG2 = exports.EXTRATOR_ARQUIVOS = exports.EXTRATOR_ID = exports.EXTRATOR_MD = exports.EXTRATOR_TS = void 0;
+exports.textoAceito = exports.UNIDADES_SCHEMA = exports.LACUNAS_SO_CONTAGEM = exports.EXTENSOES_MD = exports.EXTENSOES_TS = exports.CONFIG_SCHEMA = exports.RELATORIO_SCHEMA = exports.VERSAO_KG2 = exports.EXTRATOR_ARQUIVOS = exports.EXTRATOR_ID = exports.EXTRATOR_MD = exports.EXTRATOR_TS = void 0;
 exports.textoCurto = textoCurto;
 exports.extensaoDe = extensaoDe;
 exports.idDeBlob = idDeBlob;
@@ -34,6 +34,8 @@ exports.LACUNAS_SO_CONTAGEM = new Set([
     'chamada-fora-de-simbolo', 'chamada-nao-resolvida', 'chamada-alvo-fora-do-grafo', 'chamada-por-tipo', 'import-sem-simbolo',
     'id-sem-artefato', 'link-externo',
 ]);
+/** RM-031 KG4 (D2): as unidades por arquivo que o indice guarda para a proxima revisao reaproveitar. */
+exports.UNIDADES_SCHEMA = 'ork.graph-extraction-units/v0';
 function falha(codigo, onde) {
     throw new Error(onde ? `${codigo} em ${onde}` : codigo);
 }
@@ -136,11 +138,144 @@ const zeros = '0'.repeat(64);
 function contagemVazia(chaves) {
     return Object.fromEntries(chaves.map((k) => [k, 0]));
 }
+/**
+ * A mudanca e por conteudo: o hash de cada caminho contra o da base, mais os novos e os removidos
+ * (renome e os dois). No TypeScript, semente e o arquivo mudado ou novo e o nao mudado cuja sonda casa
+ * caminho novo ou removido; afetado e a semente e quem alcanca semente ou caminho mudado pelas
+ * dependencias gravadas na base. `package.json` ou arquivo global na mudanca extrai o TypeScript inteiro.
+ */
+function planejarReuso(base, manifesto, fontesTs, fontesMd) {
+    const porCaminho = new Map(base.arquivos.map((u) => [u.path, u]));
+    const alterados = [], novos = [], removidos = [];
+    for (const [p, m] of manifesto) {
+        const u = porCaminho.get(p);
+        if (!u)
+            novos.push(p);
+        else if (u.source_hash !== m.source_hash)
+            alterados.push(p);
+    }
+    for (const p of porCaminho.keys())
+        if (!manifesto.has(p))
+            removidos.push(p);
+    for (const l of [alterados, novos, removidos])
+        l.sort(intelligence_graph_contract_1.compararUtf8);
+    const mudados = new Set([...alterados, ...novos, ...removidos]);
+    const md = new Map();
+    for (const f of fontesMd) {
+        const u = porCaminho.get(f.path);
+        if (u?.md && !mudados.has(f.path))
+            md.set(f.path, u.md);
+    }
+    const plano = { base, porCaminho, mudanca: { alterados, novos, removidos }, md, ts: { motivo: null, sementes: new Set(), afetados: new Set() } };
+    const ordenados = [...mudados].sort(intelligence_graph_contract_1.compararUtf8), globais = new Set(base.globais_ts), ts1 = new Set(fontesTs.map((f) => f.path));
+    const pacote = ordenados.find((p) => p === 'package.json' || p.endsWith('/package.json'));
+    const global = ordenados.find((p) => globais.has(p));
+    const semUnidade = fontesTs.find((f) => !mudados.has(f.path) && !porCaminho.get(f.path)?.ts);
+    if (pacote !== undefined)
+        plano.ts.motivo = `package.json na mudanca (${pacote})`;
+    else if (global !== undefined)
+        plano.ts.motivo = `arquivo global do TypeScript na mudanca (${global})`;
+    else if (semUnidade !== undefined)
+        plano.ts.motivo = `base sem a unidade TypeScript de ${semUnidade.path}`;
+    if (plano.ts.motivo !== null)
+        return plano;
+    const existencia = [...novos, ...removidos];
+    for (const p of ts1) {
+        if (mudados.has(p))
+            plano.ts.sementes.add(p);
+        else if (existencia.length && (porCaminho.get(p)?.ts).sondas.some((b) => existencia.some((q) => (0, intelligence_graph_extract_ts_1.casaSonda)(b, q))))
+            plano.ts.sementes.add(p);
+    }
+    const dependentes = new Map();
+    for (const u of base.arquivos) {
+        for (const d of u.ts?.dependencias ?? []) {
+            const lista = dependentes.get(d);
+            if (lista)
+                lista.push(u.path);
+            else
+                dependentes.set(d, [u.path]);
+        }
+    }
+    const vistos = new Set(), fila = [...plano.ts.sementes, ...mudados];
+    while (fila.length) {
+        const q = fila.pop();
+        if (vistos.has(q))
+            continue;
+        vistos.add(q);
+        for (const x of dependentes.get(q) ?? [])
+            if (!vistos.has(x))
+                fila.push(x);
+    }
+    // CHECK (B1): quem usa um global nao importa o arquivo dele, e o global depende do que esse arquivo
+    // importa (heranca, tipo importado, `export *` atras de UMD, aumento que estende tipo de outro modulo).
+    const globalAlcancado = [...globais].sort(intelligence_graph_contract_1.compararUtf8).find((g) => vistos.has(g));
+    if (globalAlcancado !== undefined) {
+        plano.ts.motivo = `dependencia de arquivo global na mudanca (${globalAlcancado})`;
+        return plano;
+    }
+    for (const p of vistos)
+        if (ts1.has(p))
+            plano.ts.afetados.add(p);
+    return plano;
+}
+/**
+ * KG4 (D3): extrai os afetados num programa parcial: eles, os globais e o fecho direto pelas
+ * dependencias da base (a semente descobre as suas no programa, que cresce ate fechar). O resto vem
+ * da base. Afetado que passa a declarar global devolve o motivo, e o TypeScript sai inteiro.
+ */
+function extrairTsParcial(plano, entrada, extrair) {
+    const { afetados, sementes } = plano.ts, ts1 = new Set(entrada.fontes.map((f) => f.path));
+    const daBase = (p) => plano.porCaminho.get(p)?.ts;
+    const unidades = new Map(), globais = [...plano.base.globais_ts];
+    const raizes = new Set();
+    const incluir = (inicio) => {
+        const fila = [...inicio];
+        while (fila.length) {
+            const p = fila.pop();
+            if (raizes.has(p) || !ts1.has(p))
+                continue;
+            raizes.add(p);
+            if (!sementes.has(p))
+                for (const d of daBase(p).dependencias)
+                    if (!raizes.has(d))
+                        fila.push(d);
+        }
+    };
+    let r = null;
+    if (afetados.size) {
+        incluir([...afetados, ...globais]);
+        for (;;) {
+            r = extrair({ ...entrada, fontes: entrada.fontes.filter((f) => raizes.has(f.path)), emitir: afetados });
+            if (!r.faltantes.length)
+                break;
+            const antes = raizes.size;
+            incluir(r.faltantes);
+            if (raizes.size === antes)
+                falha('extracao.interna.programa-parcial');
+        }
+        const daBaseGlobal = new Set(globais), doPrograma = new Set(r.globais);
+        const novo = r.globais.find((g) => !daBaseGlobal.has(g));
+        if (novo !== undefined)
+            return { motivo: `arquivo passa a declarar global no TypeScript (${novo})`, unidades, globais, programa: raizes.size };
+        const sumiu = globais.find((g) => ts1.has(g) && !doPrograma.has(g));
+        if (sumiu !== undefined)
+            return { motivo: `global da base fora do escopo global (${sumiu})`, unidades, globais, programa: raizes.size };
+    }
+    for (const f of entrada.fontes) {
+        const u = afetados.has(f.path) ? r?.unidades.get(f.path) : daBase(f.path);
+        if (!u)
+            falha('extracao.interna.unidade-ts-ausente');
+        unidades.set(f.path, u);
+    }
+    return { motivo: null, unidades, globais, programa: raizes.size };
+}
 /**
  * Extrai o grafo das fontes fornecidas. Lanca `extracao.*` para entrada invalida ou teto do
  * contrato estourado (D10), e `grafo.*` se o resultado violar o contrato (defeito do extrator).
+ * RM-031 KG4: com `base` (as unidades do indice de outra revisao, do mesmo extrator), reextrai so o
+ * que a mudanca alcanca; o resultado e o mesmo, byte a byte, da extracao sem base.
  */
-function extrairGrafo(entrada, parser) {
+function extrairGrafo(entrada, parser, base = null) {
     const { ts, unicode, markdown, javascript } = parser;
     if (!/^[0-9]+(\.[0-9]+)*$/.test(unicode))
         falha('extracao.entrada.unicode-invalido');
@@ -224,18 +359,40 @@ function extrairGrafo(entrada, parser) {
     // B1: a raiz virtual do compilador deriva do manifesto; um caminho do repositorio nao a nomeia.
     const raiz = `/ork-${(0, intelligence_graph_contract_1.sha256DoCanonico)([...manifesto.values()].map((m) => [m.path, m.source_hash])).slice(0, 32)}`;
     const aceitaFragmento = (f) => f.length >= 1 && f.length <= intelligence_graph_contract_1.GRAFO_LIMITES.fragmento && (0, exports.textoAceito)(f);
-    juntar(semEstouro(exports.EXTRATOR_TS, () => (0, intelligence_graph_extract_ts_1.extrairTypeScript)({
-        fontes: fontesTs, arquivos: caminhos, texto, raiz, aceitaFragmento, sintaxe: javascript.sintaxe, extrator: exports.EXTRATOR_TS,
-    }, ts)));
+    const entradaTs = { fontes: fontesTs, arquivos: caminhos, texto, raiz, aceitaFragmento, sintaxe: javascript.sintaxe, extrator: exports.EXTRATOR_TS };
+    const extrairTs = (e) => semEstouro(exports.EXTRATOR_TS, () => (0, intelligence_graph_extract_ts_1.extrairTypeScript)(e, ts));
+    // KG4 (D1, D3, D4): com as unidades de uma base, so o que a mudanca alcanca e extraido de novo.
+    const plano = base ? planejarReuso(base, manifesto, fontesTs, fontesMd) : null;
+    let tsDaBase = null;
+    if (plano && plano.ts.motivo === null)
+        tsDaBase = extrairTsParcial(plano, entradaTs, extrairTs);
+    const motivoTs = plano ? plano.ts.motivo ?? tsDaBase?.motivo ?? null : null;
+    let unidadesTs, globaisTs;
+    if (tsDaBase && tsDaBase.motivo === null) {
+        unidadesTs = tsDaBase.unidades;
+        globaisTs = tsDaBase.globais;
+    }
+    else {
+        const r = extrairTs(entradaTs);
+        unidadesTs = r.unidades;
+        globaisTs = r.globais;
+    }
+    for (const f of fontesTs) {
+        const u = unidadesTs.get(f.path);
+        if (!u)
+            falha('extracao.interna.unidade-ts-ausente');
+        juntar(u.achados);
+    }
     // B4: chave `caminho#fragmento` como o frontmatter a escreve; duas refs na mesma chave ficam ambiguas.
     const simbolos = new Map();
     for (const r of achados.nos.filter((x) => x.kind === 'symbol')) {
         const chave = `${r.path}#${r.fragment}`, antes = simbolos.get(chave);
         simbolos.set(chave, antes === undefined || (antes && antes.path === r.path && antes.fragment === r.fragment) ? r : null);
     }
-    juntar(semEstouro(exports.EXTRATOR_MD, () => (0, intelligence_graph_extract_md_1.extrairMarkdown)({
-        fontes: fontesMd, codigo: fontesTs, arquivos: caminhos, simbolos, aceitaFragmento, analisar: markdown.analisar,
-        referencia: markdown.referencia, extratorMd: exports.EXTRATOR_MD, extratorId: exports.EXTRATOR_ID,
+    const estruturas = semEstouro(exports.EXTRATOR_MD, () => fontesMd.map((f) => plano?.md.get(f.path)
+        ?? (0, intelligence_graph_extract_md_1.estruturarMarkdown)(f, { aceitaFragmento, analisar: markdown.analisar, referencia: markdown.referencia })));
+    juntar(semEstouro(exports.EXTRATOR_MD, () => (0, intelligence_graph_extract_md_1.ligarMarkdown)({
+        estruturas, codigo: fontesTs, arquivos: caminhos, simbolos, aceitaFragmento, extratorMd: exports.EXTRATOR_MD, extratorId: exports.EXTRATOR_ID,
     })));
     const extratores = [
         { extractor_id: exports.EXTRATOR_ARQUIVOS, extractor_version: exports.VERSAO_KG2 },
@@ -365,5 +522,25 @@ function extrairGrafo(entrada, parser) {
         lacunas_por_categoria: Object.fromEntries([...porCategoria.entries()].sort((a, b) => (0, intelligence_graph_contract_1.compararUtf8)(a[0], b[0]))),
         lacunas: [...listadas.entries()].sort((a, b) => (0, intelligence_graph_contract_1.compararUtf8)(a[0], b[0])).map(([, l]) => l),
     };
-    return { grafo, digest, relatorio };
+    const estruturaDe = new Map(estruturas.map((x) => [x.path, x]));
+    const unidades = {
+        schema: exports.UNIDADES_SCHEMA, snapshot_id: grafo.snapshot.snapshot_id, graph_digest: digest, globais_ts: globaisTs,
+        arquivos: grafo.snapshot.source_manifest.map((m) => ({
+            path: m.path, source_hash: m.source_hash, ts: unidadesTs.get(m.path) ?? null, md: estruturaDe.get(m.path) ?? null,
+        })),
+    };
+    let reaproveitamento = null;
+    if (plano) {
+        const parcial = motivoTs === null, afetados = [...plano.ts.afetados].sort(intelligence_graph_contract_1.compararUtf8);
+        reaproveitamento = {
+            mudanca: { alterados: plano.mudanca.alterados.length, novos: plano.mudanca.novos.length, removidos: plano.mudanca.removidos.length },
+            ts: {
+                modo: !parcial ? 'inteiro' : afetados.length ? 'parcial' : 'reaproveitado', motivo: motivoTs,
+                reextraidos: parcial ? afetados : fontesTs.map((f) => f.path), programa: parcial ? tsDaBase?.programa ?? 0 : fontesTs.length,
+                reaproveitados: parcial ? fontesTs.length - afetados.length : 0,
+            },
+            md: { reextraidos: fontesMd.filter((f) => !plano.md.has(f.path)).map((f) => f.path), reaproveitados: plano.md.size },
+        };
+    }
+    return { grafo, digest, relatorio, unidades, reaproveitamento };
 }

package/dist/intelligence-graph-index.js

@@ -33,13 +33,14 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 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.versoesDoParser = exports.EXCLUSOES_DA_ARVORE = exports.MODULOS_DO_EXTRATOR = exports.PRAZO_DE_SOBRA_MS = exports.LIMITE_DE_ANCESTRAIS = exports.NOME_DE_INDICE = exports.INDICE_SCHEMA_ANTERIOR = exports.INDICE_SCHEMA = void 0;
 exports.impressaoDoExtrator = impressaoDoExtrator;
 exports.perfilDoIndice = perfilDoIndice;
 exports.chaveDoIndice = chaveDoIndice;
 exports.concessaoLocal = concessaoLocal;
 exports.pastaDoGrafo = pastaDoGrafo;
 exports.lerIndice = lerIndice;
+exports.escolherBase = escolherBase;
 exports.construirIndice = construirIndice;
 exports.indiceDoHead = indiceDoHead;
 exports.estadoDosIndices = estadoDosIndices;
@@ -61,6 +62,11 @@ exports.limparIndices = limparIndices;
  * 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.
+ *
+ * RM-031 KG4 (D1, D2, D5, D7): o indice guarda tambem as unidades por arquivo (`unidades.json`), e a
+ * construcao sem indice do HEAD parte do indice da revisao ancestral mais proxima com o mesmo perfil:
+ * reextrai so o que a mudanca alcanca e grava os mesmos bytes da extracao completa. Sem base que
+ * prove isso, extrai completo e diz por que.
  */
 const node_crypto_1 = require("node:crypto");
 const fs = __importStar(require("node:fs"));
@@ -69,9 +75,13 @@ 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';
+/** KG4 (D2): a v1 tem as unidades por arquivo; a v0 (KG3) nao serve de base e o `limpar` a remove. */
+exports.INDICE_SCHEMA = 'ork.code-graph-index/v1';
+exports.INDICE_SCHEMA_ANTERIOR = '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' };
+const ARQUIVOS = { manifesto: 'indice.json', grafo: 'grafo.json', relatorio: 'relatorio.json', unidades: 'unidades.json' };
+/** KG4 (D1): quantas revisoes, do HEAD para tras, a escolha da base percorre. */
+exports.LIMITE_DE_ANCESTRAIS = 512;
 /** 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. */
@@ -189,6 +199,31 @@ function lerPrivado(arquivo) {
         fs.closeSync(fd);
     }
 }
+/** KG4: as mesmas regras de `lerPrivado` e o tamanho do manifesto, sem ler o conteudo (a consulta nao precisa das unidades). */
+function conferirPrivado(arquivo, bytes) {
+    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));
+        }
+        if (st.size !== bytes)
+            falha('grafo.indice.corrompido', `${path.basename(arquivo)} nao bate com o tamanho`);
+    }
+    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 {
@@ -213,7 +248,11 @@ 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_ANTERIOR) {
+        falha('grafo.indice.formato-anterior', `${exports.INDICE_SCHEMA_ANTERIOR} (KG3), sem unidades; o ork grafo limpar o remove`);
+    }
     if (!o || typeof o !== 'object' || o.schema !== exports.INDICE_SCHEMA || o.chave !== chave || o.graph_schema !== intelligence_graph_contract_1.GRAFO_SCHEMA
+        || o.units_schema !== intelligence_graph_extract_1.UNIDADES_SCHEMA || !HEX64.test(o.units_digest) || !inteiro(o.units_bytes)
         || 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'
@@ -259,7 +298,27 @@ function lerIndice(ctx, chave, opcoes = {}) {
         }
     }
     const relatorio = opcoes.relatorio ? JSON.parse(bytesDoRelatorio.toString('utf8')) : null;
-    return { dir, manifesto, grafo, relatorio };
+    // KG4: as unidades so sao lidas (e o digest conferido) por quem as usa; a consulta confere so o tamanho.
+    let unidades = null;
+    if (opcoes.unidades) {
+        let u;
+        try {
+            u = JSON.parse(conferido(ARQUIVOS.unidades, manifesto.units_bytes, manifesto.units_digest).toString('utf8'));
+        }
+        catch (e) {
+            if (e instanceof SyntaxError)
+                falha('grafo.indice.corrompido', 'unidades.json');
+            throw e;
+        }
+        if (!u || u.schema !== intelligence_graph_extract_1.UNIDADES_SCHEMA || u.snapshot_id !== manifesto.snapshot_id || u.graph_digest !== manifesto.graph_digest
+            || !Array.isArray(u.arquivos) || !Array.isArray(u.globais_ts)) {
+            falha('grafo.indice.corrompido', 'unidades.json fora do manifesto');
+        }
+        unidades = u;
+    }
+    else
+        conferirPrivado(path.join(dir, ARQUIVOS.unidades), manifesto.units_bytes);
+    return { dir, manifesto, grafo, relatorio, unidades };
 }
 /** Embaralhamento reproduzivel (LCG): a permutacao da verificacao nao depende de acaso. */
 function embaralhar(itens, semente) {
@@ -296,11 +355,88 @@ function removerPasta(grafoDir, nome) {
         fs.renameSync(alvo, lixo);
     fs.rmSync(lixo, { recursive: true, force: true });
 }
+/** O perfil que um manifesto guarda: tudo o que entra na chave, menos a revisao. */
+const perfilDoManifesto = (m) => ({
+    repository_id: m.repository_id, tenant_id: m.tenant_id, acl_refs: m.acl_refs, analisadores: m.analisadores, pacotes: m.pacotes, codigo: m.codigo,
+});
+const curta = (r) => r.slice(0, 12);
+/**
+ * KG4 (D1, D5): a base e o indice da revisao ancestral mais proxima do HEAD (nas `LIMITE_DE_ANCESTRAIS`
+ * do `git rev-list`) com o mesmo perfil. Sem ela, o motivo diz o que havia: indice ancestral de outro
+ * extrator, indice do mesmo extrator fora da linha do HEAD (historico reescrito ou outro ramo), indice
+ * de formato anterior, ou nenhum. Base que nao passa na leitura e trocada pela proxima, com o erro.
+ */
+function escolherBase(ctx, perfil, head, raiz) {
+    let dir;
+    try {
+        dir = pastaDoGrafo(ctx, false);
+    }
+    catch (e) {
+        if (e.message === 'grafo.indice.ausente')
+            return { base: null, motivo: 'nenhum indice guardado' };
+        throw e;
+    }
+    const posicao = new Map((0, intelligence_graph_repo_1.revisoesAncestrais)(raiz, exports.LIMITE_DE_ANCESTRAIS).map((r, i) => [r, i]));
+    const desejado = (0, intelligence_graph_contract_1.canonico)(perfil), identidade = (0, intelligence_graph_contract_1.canonico)([perfil.repository_id, perfil.tenant_id, perfil.acl_refs]);
+    const candidatos = [];
+    let outroExtrator = null, foraDaLinha = null, anterior = false;
+    for (const nome of fs.readdirSync(dir).sort(intelligence_graph_contract_1.compararUtf8)) {
+        if (!exports.NOME_DE_INDICE.test(nome))
+            continue;
+        let m;
+        try {
+            pastaPrivada(path.join(dir, nome), false);
+            m = manifestoValido(JSON.parse(lerPrivado(path.join(dir, nome, ARQUIVOS.manifesto)).toString('utf8')), nome);
+        }
+        catch (e) {
+            if (e.message.startsWith('grafo.indice.formato-anterior'))
+                anterior = true;
+            continue;
+        }
+        if (m.revision === head)
+            continue;
+        const p = perfilDoManifesto(m), i = posicao.get(m.revision);
+        if ((0, intelligence_graph_contract_1.canonico)(p) === desejado) {
+            if (i === undefined)
+                foraDaLinha ??= m.revision;
+            else
+                candidatos.push({ chave: nome, revision: m.revision, posicao: i });
+        }
+        else if (i !== undefined && (0, intelligence_graph_contract_1.canonico)([p.repository_id, p.tenant_id, p.acl_refs]) === identidade && (!outroExtrator || i < outroExtrator.posicao)) {
+            const campos = ['analisadores', 'pacotes', 'codigo'].filter((k) => (0, intelligence_graph_contract_1.canonico)(p[k]) !== (0, intelligence_graph_contract_1.canonico)(perfil[k]));
+            outroExtrator = { revision: m.revision, campos, posicao: i };
+        }
+    }
+    const erros = [];
+    for (const c of candidatos.sort((a, b) => a.posicao - b.posicao)) {
+        try {
+            const lido = lerIndice(ctx, c.chave, { grafo: false, unidades: true });
+            return { base: { revision: c.revision, chave: c.chave, unidades: lido.unidades }, motivo: null };
+        }
+        catch (e) {
+            erros.push(`${curta(c.revision)}: ${e.message}`);
+        }
+    }
+    if (erros.length)
+        return { base: null, motivo: `base ilegivel (${erros.join('; ')})` };
+    const motivos = [];
+    if (foraDaLinha) {
+        motivos.push(`nenhum indice de revisao ancestral nas ultimas ${exports.LIMITE_DE_ANCESTRAIS}; o de ${curta(foraDaLinha)} nao esta entre elas (historico reescrito, outro ramo ou revisao mais antiga)`);
+    }
+    if (outroExtrator)
+        motivos.push(`o extrator mudou desde o indice de ${curta(outroExtrator.revision)} (${outroExtrator.campos.join(', ')})`);
+    if (!motivos.length && anterior)
+        motivos.push(`so ha indice de formato anterior (${exports.INDICE_SCHEMA_ANTERIOR})`);
+    return { base: null, motivo: motivos.length ? motivos.join('; ') : 'nenhum indice de revisao ancestral com este extrator' };
+}
+const textoDasUnidades = (u) => JSON.stringify(u);
 /**
- * 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.
+ * Constroi o indice do HEAD limpo, ou confirma o que ja existe. Sem o indice do HEAD, parte do indice
+ * ancestral com o mesmo perfil (KG4) e reextrai so o que a mudanca alcanca; sem base, ou se o
+ * incremental falha, extrai completo e diz por que. `--forcar` extrai completo e so troca os arquivos se
+ * o conteudo mudou; `--verificar` extrai completo, prova o determinismo com a ordem de leitura trocada,
+ * compara com o incremental quando ha base e reprova se o guardado integro difere; indice que nao passa
+ * na leitura e substituido. O incremental passa pelas mesmas validacoes da completa antes de publicar.
  */
 function construirIndice(ctx, opcoes = {}) {
     const inicio = process.hrtime.bigint();
@@ -308,10 +444,11 @@ function construirIndice(ctx, opcoes = {}) {
     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 head = arvore.head;
     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 chave = chaveDoIndice(head, perfil);
     const grafoDir = pastaDoGrafo(ctx, true);
     const final = path.join(grafoDir, chave);
     let motivo = null;
@@ -320,55 +457,96 @@ function construirIndice(ctx, opcoes = {}) {
         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() };
+            if (!opcoes.forcar && !opcoes.verificar) {
+                return {
+                    estado: 'existente', motivo: null, chave, dir: final, manifesto: atual.manifesto, determinismo: null, ms: ms(),
+                    modo: null, base: null, motivo_completo: null, reaproveitamento: null, incremental: null,
+                };
+            }
         }
         catch (e) {
             motivo = e.message;
         }
     }
     const entrada = (0, intelligence_graph_repo_1.lerRepositorio)(arvore.raiz, leitura);
-    if (entrada.revision !== arvore.head)
+    if (entrada.revision !== 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);
+    // KG4 (D1, D5, D7): a base, salvo com `--forcar`.
+    let base = null, motivoCompleto = 'pedido com --forcar';
+    if (!opcoes.forcar)
+        ({ base, motivo: motivoCompleto } = escolherBase(ctx, perfil, head, arvore.raiz));
+    let r = null, modo = 'completo';
+    if (base && !opcoes.verificar) {
+        try {
+            r = (0, intelligence_graph_extract_1.extrairGrafo)(entrada, parser, base.unidades);
+            modo = 'incremental';
+        }
+        catch (e) {
+            // O incremental nunca impede o indice: a completa decide, e o motivo fica dito.
+            motivoCompleto = `o incremental a partir de ${curta(base.revision)} falhou e a extracao foi completa (${e.message})`;
+            r = null;
+        }
+    }
+    if (!r)
+        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);
+    // KG4 (D6): `r.grafo` e o retorno de `validarGrafo` dentro da extracao; validar de novo so repetiria.
+    const conferencia = (0, intelligence_graph_contract_1.conferirFontesDoGrafoValidado)(r.grafo, fornecidas);
     if (conferencia.estado !== 'verificada' || conferencia.evidenciasIndisponiveis > 0)
         falha('grafo.indice.fontes-nao-conferidas');
-    let determinismo = null;
+    const textoDoGrafo = (0, intelligence_graph_contract_1.canonico)(r.grafo), textoDoRelatorio = (0, intelligence_graph_contract_1.canonico)(r.relatorio), unidades = textoDasUnidades(r.unidades);
+    if (sha256(textoDoGrafo) !== r.digest)
+        falha('grafo.indice.digest-divergente');
+    let determinismo = null, incremental = null;
     if (opcoes.verificar) {
-        const relatorio = (0, intelligence_graph_contract_1.sha256DoCanonico)(r.relatorio);
+        const relatorio = sha256(textoDoRelatorio), dasUnidades = sha256(unidades);
         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 doOutro = (0, intelligence_graph_contract_1.sha256DoCanonico)(outra.relatorio), unidadesDoOutro = sha256(textoDasUnidades(outra.unidades));
+            return {
+                ordem, digest: outra.digest, relatorio: doOutro, unidades: unidadesDoOutro,
+                igual: outra.digest === r.digest && doOutro === relatorio && unidadesDoOutro === dasUnidades,
+            };
         });
         const diferente = determinismo.find((d) => !d.igual);
         if (diferente)
             falha('grafo.indice.nao-deterministico', diferente.ordem);
+        if (base) {
+            // KG4 (D7): a prova no repositorio de quem usa: o incremental da base da os mesmos bytes da completa.
+            let inc;
+            try {
+                inc = (0, intelligence_graph_extract_1.extrairGrafo)(entrada, parser, base.unidades);
+            }
+            catch (e) {
+                falha('grafo.indice.incremental-divergente', `o incremental da base ${curta(base.revision)} falhou: ${e.message}`);
+            }
+            const igual = (0, intelligence_graph_contract_1.canonico)(inc.grafo) === textoDoGrafo && (0, intelligence_graph_contract_1.canonico)(inc.relatorio) === textoDoRelatorio && textoDasUnidades(inc.unidades) === unidades;
+            if (!igual)
+                falha('grafo.indice.incremental-divergente', `base ${curta(base.revision)}`);
+            incremental = { base: base.revision, igual, reaproveitamento: inc.reaproveitamento };
+        }
     }
-    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,
+        schema: exports.INDICE_SCHEMA, chave, revision: 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 },
+        units_schema: intelligence_graph_extract_1.UNIDADES_SCHEMA, units_digest: sha256(unidades), units_bytes: Buffer.byteLength(unidades, 'utf8'),
     };
     const conteudos = {
-        [ARQUIVOS.manifesto]: (0, intelligence_graph_contract_1.canonico)(manifesto), [ARQUIVOS.grafo]: textoDoGrafo, [ARQUIVOS.relatorio]: textoDoRelatorio,
+        [ARQUIVOS.manifesto]: (0, intelligence_graph_contract_1.canonico)(manifesto), [ARQUIVOS.grafo]: textoDoGrafo, [ARQUIVOS.relatorio]: textoDoRelatorio, [ARQUIVOS.unidades]: unidades,
     };
+    const daBase = modo === 'incremental' && base ? { revision: base.revision, chave: base.chave } : opcoes.verificar && base ? { revision: base.revision, chave: base.chave } : null;
     const tmp = path.join(grafoDir, `.tmp-${(0, node_crypto_1.randomUUID)()}`);
     pastaPrivada(tmp, true);
     try {
@@ -376,7 +554,10 @@ function construirIndice(ctx, opcoes = {}) {
             gravarPrivado(path.join(tmp, nome), texto);
         sincronizarPasta(tmp);
         opcoes.antesDePublicar?.();
-        const resultado = (estado) => ({ estado, motivo, chave, dir: final, manifesto, determinismo, ms: ms() });
+        const resultado = (estado) => ({
+            estado, motivo, chave, dir: final, manifesto, determinismo, ms: ms(), modo, base: daBase,
+            motivo_completo: modo === 'incremental' ? null : motivoCompleto, reaproveitamento: r?.reaproveitamento ?? null, incremental,
+        });
         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 });

package/dist/intelligence-graph-parsers.js

@@ -46,10 +46,12 @@ exports.carregarAnalisadores = carregarAnalisadores;
  * `typescript` e os pacotes do micromark so valem dentro da instalacao do `ork` que roda (o
  * `node_modules` do pacote `@orkastery/cli` que contem este modulo), nunca do diretorio atual, do
  * `NODE_PATH` nem de uma pasta acima, como a do projeto que instalou o `ork` como dependencia: o
- * repositorio lido e dado, e codigo dele nunca e carregado. Eles nao sao dependencias de runtime do
- * pacote publicado (D1: dependencia nova e decisao de produto); onde faltam ou estao fora da
- * instalacao, a recusa e `grafo.parser.indisponivel: <pacote>`. `pacotesDosAnalisadores` lista o
- * fecho de dependencias deles, com versao, para a chave do indice (CHECK rodada 1, A10).
+ * repositorio lido e dado, e codigo dele nunca e carregado. Desde a correcao de empacotamento da
+ * RM-031 eles sao dependencias de runtime do pacote publicado, com versao exata, e o
+ * `npm install -g` os poe dentro da instalacao; onde faltam ou estao fora dela (o `ork` instalado
+ * dentro de um projeto ou pelo `npx`, que icam as dependencias), a recusa e
+ * `grafo.parser.indisponivel: <pacote>`, e o `ork doctor` diz a correcao. `pacotesDosAnalisadores`
+ * lista o fecho de dependencias deles, com versao, para a chave do indice (CHECK rodada 1, A10).
  *
  * O juiz de sintaxe e o V8 do Node que roda a extracao, o mesmo que carregaria o arquivo. CommonJS
  * compila aqui, em funcao com as variaveis do modulo, como o carregador faz. ESM compila num unico

package/dist/intelligence-graph-repo.js

@@ -37,6 +37,7 @@ exports.TENANT_PADRAO = void 0;
 exports.identidadeDaLeitura = identidadeDaLeitura;
 exports.revisaoDaArvore = revisaoDaArvore;
 exports.headsDasArvores = headsDasArvores;
+exports.revisoesAncestrais = revisoesAncestrais;
 exports.lerRepositorio = lerRepositorio;
 /**
  * RM-031 KG2 (D8): leitura do repositorio Git local para o extrator. E a unica borda de E/S do
@@ -118,6 +119,15 @@ function headsDasArvores(diretorio) {
     const saida = obrigatorio(diretorio, ['worktree', 'list', '--porcelain']).toString('utf8');
     return [...new Set(saida.split('\n').filter((l) => /^HEAD [0-9a-f]{40,64}$/.test(l)).map((l) => l.slice(5)))].sort();
 }
+/**
+ * RM-031 KG4 (D1): o HEAD e as revisoes ancestrais dele (`git rev-list`), da mais recente para a mais
+ * antiga, ate o limite. Sem commit, ou com o Git falhando, nao ha ancestral.
+ */
+function revisoesAncestrais(diretorio, limite) {
+    const raiz = obrigatorio(diretorio, ['rev-parse', '--show-toplevel']).toString('utf8').trim();
+    const r = git(raiz, ['rev-list', `--max-count=${Math.max(1, Math.floor(limite))}`, 'HEAD']);
+    return r.ok ? r.saida.toString('utf8').split('\n').filter((l) => /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(l)) : [];
+}
 /** Le o repositorio que contem `diretorio` e devolve a entrada do extrator. */
 function lerRepositorio(diretorio, opcoes = {}) {
     const raiz = obrigatorio(diretorio, ['rev-parse', '--show-toplevel']).toString('utf8').trim();