@orkastery/cli 0.4.3 → 0.5.0

package/dist/intelligence-graph-contract.js

@@ -0,0 +1,577 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.digestDoGrafo = exports.digestDosExtratores = exports.sha256DoCanonico = exports.grafoSchema = exports.diagnosticoSchema = exports.arestaSchema = exports.noSchema = exports.evidenciaSchema = exports.spanSchema = exports.spanDePdfSchema = exports.spanDeTextoSchema = exports.snapshotSchema = exports.extratorSchema = exports.entradaDoManifestoSchema = exports.acessoSchema = exports.MATRIZ_DE_ARESTAS = exports.ESQUEMAS_DE_AUTORIDADE_RESERVADOS = exports.TIPOS_DE_DIAGNOSTICO = exports.CLASSE_DE_CONFIANCA = exports.METODOS_DE_EXTRACAO = exports.TIPOS_DE_ARESTA = exports.TIPOS_DE_NO = exports.GRAFO_LIMITES = exports.GRAFO_SCHEMA = void 0;
+exports.compararUtf8 = compararUtf8;
+exports.canonico = canonico;
+exports.idDoSnapshot = idDoSnapshot;
+exports.idDoNo = idDoNo;
+exports.idDaAresta = idDaAresta;
+exports.derivarIds = derivarIds;
+exports.caminhoValido = caminhoValido;
+exports.validarGrafo = validarGrafo;
+exports.conferirFontes = conferirFontes;
+/**
+ * I-31 KG1 (D1 a D5, D9, D10): contrato `ork.code-artifact-graph/v1` do grafo deterministico
+ * de codigo e artefatos.
+ *
+ * O grafo e projecao local e descartavel: a mesma entrada, configuracao e versao de extrator
+ * determinam as mesmas identidades e o mesmo conteudo canonico, em qualquer ordem de insercao.
+ * Modulo puro (D10): sem filesystem, rede, subprocesso, parser, banco ou modelo. Bytes de fonte
+ * chegam por argumento. Nao amplia o Company Brain v1 nem pluga o adaptador semantico (D9).
+ */
+const node_crypto_1 = require("node:crypto");
+const zod_1 = require("zod");
+exports.GRAFO_SCHEMA = 'ork.code-artifact-graph/v1';
+/** Tetos do contrato: acima deles o payload e recusado, nunca truncado. */
+exports.GRAFO_LIMITES = Object.freeze({
+    manifesto: 100_000, nos: 100_000, arestas: 500_000, evidenciasPorAresta: 64, aclRefs: 32,
+    extratores: 32, diagnosticos: 100_000, caminho: 1024, fragmento: 512, paginas: 100_000,
+});
+exports.TIPOS_DE_NO = ['file', 'symbol', 'section', 'artifact'];
+exports.TIPOS_DE_ARESTA = ['contains', 'declares', 'imports', 'calls', 'references', 'derived_from'];
+/** D4: so metodo deterministico sustenta aresta. Embedding, similaridade e inferencia ficam fora. */
+exports.METODOS_DE_EXTRACAO = ['ast', 'structured', 'explicit-link', 'text-location'];
+exports.CLASSE_DE_CONFIANCA = 'EXTRACTED';
+/** D3: o que o extrator nao resolveu vira diagnostico, nunca aresta nem no externo fabricado. */
+exports.TIPOS_DE_DIAGNOSTICO = ['unresolved-import', 'dynamic-resolution', 'unsupported-language'];
+/** D4: o indice nao e autoridade de fato. Estes esquemas de autoridade apontam para o proprio grafo. */
+exports.ESQUEMAS_DE_AUTORIDADE_RESERVADOS = ['graph', 'index', 'kg', 'snap', 'node', 'edge'];
+const nenhum = [];
+/** D3: matriz fechada, tipo de origem para os tipos de destino permitidos. */
+exports.MATRIZ_DE_ARESTAS = Object.freeze({
+    contains: { file: ['section'], symbol: ['symbol'], section: nenhum, artifact: nenhum },
+    declares: { file: ['symbol'], symbol: nenhum, section: nenhum, artifact: nenhum },
+    imports: { file: ['file', 'symbol'], symbol: ['file', 'symbol'], section: nenhum, artifact: nenhum },
+    calls: { file: nenhum, symbol: ['symbol'], section: nenhum, artifact: nenhum },
+    references: { file: exports.TIPOS_DE_NO, symbol: exports.TIPOS_DE_NO, section: exports.TIPOS_DE_NO, artifact: exports.TIPOS_DE_NO },
+    derived_from: { file: nenhum, symbol: nenhum, section: nenhum, artifact: ['file', 'section', 'artifact'] },
+});
+const inteiro = zod_1.z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+const linha = zod_1.z.number().int().min(1).max(Number.MAX_SAFE_INTEGER).nullable();
+const sha256 = zod_1.z.string().regex(/^[a-f0-9]{64}$/);
+const idDeSnapshot = zod_1.z.string().regex(/^snap-[a-f0-9]{64}$/);
+const idDeNo = zod_1.z.string().regex(/^node-[a-f0-9]{64}$/);
+const idDeAresta = zod_1.z.string().regex(/^edge-[a-f0-9]{64}$/);
+const tenant = zod_1.z.string().regex(/^[a-z0-9][a-z0-9._-]{0,63}$/);
+const aclRef = zod_1.z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,159}$/);
+const autoridade = zod_1.z.string().regex(/^[a-z][a-z0-9+.-]{0,31}:[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$/);
+const versaoDaFonte = zod_1.z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:+-]{0,127}$/);
+const idDeExtrator = zod_1.z.string().regex(/^[a-z][a-z0-9._-]{0,63}$/);
+const versaoDeExtrator = zod_1.z.string().regex(/^[0-9A-Za-z][0-9A-Za-z.+-]{0,63}$/);
+const caminho = zod_1.z.string().min(1).max(exports.GRAFO_LIMITES.caminho);
+const textoCurto = zod_1.z.string().min(1).max(exports.GRAFO_LIMITES.fragmento);
+/** D5: restricao de acesso. Referencias ordenadas, sem repeticao; nenhuma concede permissao. */
+exports.acessoSchema = zod_1.z.object({
+    tenant_id: tenant, acl_refs: zod_1.z.array(aclRef).min(1).max(exports.GRAFO_LIMITES.aclRefs),
+}).strict();
+exports.entradaDoManifestoSchema = zod_1.z.object({
+    path: caminho, authority: autoridade, source_hash: sha256, source_version: versaoDaFonte,
+    size_bytes: inteiro, access: exports.acessoSchema,
+}).strict();
+exports.extratorSchema = zod_1.z.object({ extractor_id: idDeExtrator, extractor_version: versaoDeExtrator }).strict();
+/** D2: snapshot e manifesto, configuracao e extratores. Nome de branch nao identifica entrada. */
+exports.snapshotSchema = zod_1.z.object({
+    snapshot_id: idDeSnapshot,
+    revision: zod_1.z.string().regex(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/).nullable(),
+    revision_unavailable_reason: zod_1.z.string().regex(/^[a-z][a-z0-9-]{0,63}$/).nullable(),
+    source_manifest: zod_1.z.array(exports.entradaDoManifestoSchema).min(1).max(exports.GRAFO_LIMITES.manifesto),
+    config_hash: sha256,
+    extractors: zod_1.z.array(exports.extratorSchema).min(1).max(exports.GRAFO_LIMITES.extratores),
+    extractors_digest: sha256,
+}).strict();
+/** D4: offsets em bytes UTF-8 da fonte, inicio inclusivo e fim exclusivo. */
+exports.spanDeTextoSchema = zod_1.z.object({
+    type: zod_1.z.literal('text'), byte_start: inteiro, byte_end: inteiro, line_start: linha, line_end: linha,
+}).strict();
+/** D4: offsets no texto UTF-8 extraido da pagina, nunca no binario do PDF. */
+exports.spanDePdfSchema = zod_1.z.object({
+    type: zod_1.z.literal('pdf-text'), page: zod_1.z.number().int().min(1).max(exports.GRAFO_LIMITES.paginas),
+    byte_start: inteiro, byte_end: inteiro, extracted_text_hash: sha256,
+}).strict();
+exports.spanSchema = zod_1.z.discriminatedUnion('type', [exports.spanDeTextoSchema, exports.spanDePdfSchema]);
+exports.evidenciaSchema = zod_1.z.object({
+    snapshot_id: idDeSnapshot, path: caminho, source_hash: sha256, source_version: versaoDaFonte,
+    authority: autoridade, extractor_id: idDeExtrator, extractor_version: versaoDeExtrator,
+    extraction_method: zod_1.z.enum(exports.METODOS_DE_EXTRACAO), confidence_class: zod_1.z.literal(exports.CLASSE_DE_CONFIANCA),
+    span: exports.spanSchema, access: exports.acessoSchema,
+}).strict();
+exports.noSchema = zod_1.z.object({
+    node_id: idDeNo, kind: zod_1.z.enum(exports.TIPOS_DE_NO), snapshot_id: idDeSnapshot,
+    locator: zod_1.z.object({ path: caminho, fragment: textoCurto.nullable() }).strict(),
+    source_hash: sha256, access: exports.acessoSchema,
+}).strict();
+exports.arestaSchema = zod_1.z.object({
+    edge_id: idDeAresta, kind: zod_1.z.enum(exports.TIPOS_DE_ARESTA), snapshot_id: idDeSnapshot, from: idDeNo, to: idDeNo,
+    evidence: zod_1.z.array(exports.evidenciaSchema).min(1).max(exports.GRAFO_LIMITES.evidenciasPorAresta), access: exports.acessoSchema,
+}).strict();
+exports.diagnosticoSchema = zod_1.z.object({
+    kind: zod_1.z.enum(exports.TIPOS_DE_DIAGNOSTICO), path: caminho, reference: textoCurto.nullable(),
+    extractor_id: idDeExtrator, extractor_version: versaoDeExtrator, access: exports.acessoSchema,
+}).strict();
+exports.grafoSchema = zod_1.z.object({
+    schema: zod_1.z.literal(exports.GRAFO_SCHEMA), tenant_id: tenant,
+    repository_id: zod_1.z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/),
+    snapshot: exports.snapshotSchema,
+    nodes: zod_1.z.array(exports.noSchema).max(exports.GRAFO_LIMITES.nos),
+    edges: zod_1.z.array(exports.arestaSchema).max(exports.GRAFO_LIMITES.arestas),
+    diagnostics: zod_1.z.array(exports.diagnosticoSchema).max(exports.GRAFO_LIMITES.diagnosticos),
+}).strict();
+/** O erro traz o codigo e a posicao estrutural, nunca conteudo de fonte. */
+function falha(codigo, onde) {
+    throw new Error(onde ? `${codigo} em ${onde}` : codigo);
+}
+/**
+ * Ordem de code points, que e a ordem dos bytes UTF-8: nao depende da linguagem do consumidor.
+ * Unidade UTF-16 de surrogate (D800-DFFF) representa code point acima de FFFF e vai para o fim.
+ */
+function compararUtf8(a, b) {
+    const ajuste = (c) => (c >= 0xe000 ? c - 0x800 : c >= 0xd800 ? c + 0x2000 : c);
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        const x = a.charCodeAt(i), y = b.charCodeAt(i);
+        if (x !== y)
+            return ajuste(x) - ajuste(y);
+    }
+    return a.length - b.length;
+}
+/** D2: JSON canonico. Chaves na ordem de bytes UTF-8, sem espaco, so numero finito. */
+function canonico(v) {
+    if (v === null || typeof v === 'boolean' || typeof v === 'string')
+        return JSON.stringify(v);
+    if (typeof v === 'number')
+        return Number.isFinite(v) ? JSON.stringify(v) : falha('grafo.canonico.numero-invalido');
+    if (Array.isArray(v))
+        return `[${v.map(canonico).join(',')}]`;
+    if (typeof v === 'object') {
+        const o = v;
+        return `{${Object.keys(o).sort(compararUtf8).map((k) => `${JSON.stringify(k)}:${canonico(o[k])}`).join(',')}}`;
+    }
+    return falha('grafo.canonico.tipo-invalido');
+}
+/** SHA-256 sobre os bytes UTF-8 do conteudo canonico. */
+const sha256DoCanonico = (v) => (0, node_crypto_1.createHash)('sha256').update(canonico(v), 'utf8').digest('hex');
+exports.sha256DoCanonico = sha256DoCanonico;
+const sha256DosBytes = (b) => (0, node_crypto_1.createHash)('sha256').update(b).digest('hex');
+/** Ordena conjunto por chave estavel, calculando cada chave uma vez. */
+function ordenado(itens, chave) {
+    return itens.map((item) => [chave(item), item]).sort((a, b) => compararUtf8(a[0], b[0])).map(([, item]) => item);
+}
+const digestDosExtratores = (extratores) => (0, exports.sha256DoCanonico)(ordenado(extratores, (e) => e.extractor_id));
+exports.digestDosExtratores = digestDosExtratores;
+/** D2: o snapshot deriva de tenant, repositorio, revisao, manifesto, configuracao e extratores. */
+function idDoSnapshot(g) {
+    const s = g.snapshot;
+    return `snap-${(0, exports.sha256DoCanonico)({
+        schema: exports.GRAFO_SCHEMA, tenant_id: g.tenant_id, repository_id: g.repository_id,
+        revision: s.revision, revision_unavailable_reason: s.revision_unavailable_reason,
+        source_manifest: ordenado(s.source_manifest, (m) => m.path), config_hash: s.config_hash,
+        extractors: ordenado(s.extractors, (e) => e.extractor_id),
+    })}`;
+}
+/** D2: o no deriva de tenant, repositorio, snapshot, tipo e localizador. */
+function idDoNo(tenantId, repositoryId, snapshotId, kind, locator) {
+    return `node-${(0, exports.sha256DoCanonico)({ tenant_id: tenantId, repository_id: repositoryId, snapshot_id: snapshotId, kind, locator })}`;
+}
+/** D2: a aresta deriva de snapshot, tipo, extremidades e evidencias canonicas. */
+function idDaAresta(a) {
+    return `edge-${(0, exports.sha256DoCanonico)({ snapshot_id: a.snapshot_id, kind: a.kind, from: a.from, to: a.to, evidence: ordenado(a.evidence, canonico) })}`;
+}
+function canonizar(g) {
+    return {
+        ...g,
+        snapshot: {
+            ...g.snapshot,
+            source_manifest: ordenado(g.snapshot.source_manifest, (m) => m.path),
+            extractors: ordenado(g.snapshot.extractors, (e) => e.extractor_id),
+        },
+        nodes: ordenado(g.nodes, (n) => n.node_id),
+        edges: ordenado(g.edges.map((a) => ({ ...a, evidence: ordenado(a.evidence, canonico) })), (a) => a.edge_id),
+        diagnostics: ordenado(g.diagnostics, canonico),
+    };
+}
+/**
+ * Para o produtor (KG2): recalcula snapshot, nos e arestas a partir do conteudo, reescrevendo
+ * as extremidades pelo id provisorio de cada no. Nao valida; o resultado passa por validarGrafo.
+ */
+function derivarIds(rascunho) {
+    const g = structuredClone(rascunho), s = g.snapshot;
+    s.extractors_digest = (0, exports.digestDosExtratores)(s.extractors);
+    s.snapshot_id = idDoSnapshot(g);
+    const novos = new Map();
+    for (const n of g.nodes) {
+        // Id provisorio repetido tornaria ambigua a extremidade: recusa em vez de escolher um.
+        if (novos.has(n.node_id))
+            falha('grafo.id.provisorio-duplicado');
+        n.snapshot_id = s.snapshot_id;
+        const id = idDoNo(g.tenant_id, g.repository_id, s.snapshot_id, n.kind, n.locator);
+        novos.set(n.node_id, id);
+        n.node_id = id;
+    }
+    for (const a of g.edges) {
+        a.snapshot_id = s.snapshot_id;
+        a.from = novos.get(a.from) ?? a.from;
+        a.to = novos.get(a.to) ?? a.to;
+        for (const e of a.evidence)
+            e.snapshot_id = s.snapshot_id;
+        a.edge_id = idDaAresta(a);
+    }
+    return canonizar(g);
+}
+/**
+ * Controle C0 e C1, controles bidirecionais e marcas invisiveis sem uso em nome (hifen suave,
+ * espaco de largura zero, juntores de palavra, BOM), que fazem um nome parecer outro. ZWJ e ZWNJ
+ * ficam: emoji e escritas como a persa e as indicas dependem deles.
+ */
+const CONTROLE = /[\u0000-\u001f\u007f-\u009f\u00ad\u061c\u180e\u200b\u200e\u200f\u2028\u2029\u202a-\u202e\u2060-\u206f\ufeff\ufff9-\ufffb]/;
+const SURROGATE_ISOLADO = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+const textoValido = (t) => !CONTROLE.test(t) && !SURROGATE_ISOLADO.test(t);
+/**
+ * D2: caminho relativo a raiz declarada, com "/" e caixa preservada. O contrato compara caminhos
+ * como texto e nao normaliza: forma ambigua e recusada, para dois caminhos distintos nunca se
+ * fundirem em silencio. Escape percentual (`%2e`, `%252e`) e recusado inteiro, porque um
+ * consumidor que decodifica uma ou duas vezes chegaria a outro caminho. Primeiro segmento com
+ * ":" parece esquema de URL ou drive e tambem e recusado.
+ */
+function caminhoValido(p) {
+    if (!p || !textoValido(p) || p.includes('\\') || p.startsWith('/') || /%[0-9A-Fa-f]{2}/.test(p))
+        return false;
+    const segmentos = p.split('/');
+    if (segmentos[0].includes(':'))
+        return false;
+    return segmentos.every((segmento) => segmento !== '' && segmento !== '.' && segmento !== '..');
+}
+const autoridadeDoIndice = (a) => exports.ESQUEMAS_DE_AUTORIDADE_RESERVADOS.includes(a.slice(0, a.indexOf(':')));
+function contem(maior, menor) {
+    const s = new Set(maior);
+    for (const x of menor)
+        if (!s.has(x))
+            return false;
+    return true;
+}
+function conferirAcesso(a, tenantId, onde) {
+    if (a.tenant_id !== tenantId)
+        falha('grafo.acesso.tenant-divergente', onde);
+    for (let i = 1; i < a.acl_refs.length; i++) {
+        const c = compararUtf8(a.acl_refs[i - 1], a.acl_refs[i]);
+        if (c === 0)
+            falha('grafo.acesso.acl-duplicada', onde);
+        if (c > 0)
+            falha('grafo.acesso.acl-fora-de-ordem', onde);
+    }
+}
+const chaveDoExtrator = (id, versao) => `${id}@${versao}`;
+function conferirEvidencia(e, c, onde) {
+    if (e.snapshot_id !== c.snapshotId)
+        falha('grafo.snapshot.divergente', onde);
+    if (!caminhoValido(e.path))
+        falha('grafo.caminho.invalido', onde);
+    const m = c.manifesto.get(e.path);
+    if (!m)
+        falha('grafo.proveniencia.fonte-ausente', onde);
+    if (e.source_hash !== m.source_hash || e.source_version !== m.source_version)
+        falha('grafo.proveniencia.fonte-divergente', onde);
+    if (autoridadeDoIndice(e.authority))
+        falha('grafo.proveniencia.autoridade-indice', onde);
+    if (e.authority !== m.authority)
+        falha('grafo.proveniencia.autoridade-divergente', onde);
+    if (!c.extratores.has(chaveDoExtrator(e.extractor_id, e.extractor_version)))
+        falha('grafo.proveniencia.extrator-nao-fixado', onde);
+    const s = e.span;
+    if (s.byte_start >= s.byte_end)
+        falha('grafo.span.intervalo-invalido', onde);
+    if (s.type === 'text') {
+        if (s.byte_end > m.size_bytes)
+            falha('grafo.span.fora-da-fonte', onde);
+        if ((s.line_start === null) !== (s.line_end === null) || (s.line_start !== null && s.line_end !== null && s.line_start > s.line_end)) {
+            falha('grafo.span.linhas-invalidas', onde);
+        }
+    }
+    conferirAcesso(e.access, c.tenantId, onde);
+    if (!contem(e.access.acl_refs, m.access.acl_refs))
+        falha('grafo.acesso.restricao-omitida', onde);
+}
+/** Hierarquia `contains` sem ciclo, em profundidade iterativa para nao estourar a pilha. */
+function semCiclo(filhos) {
+    const estado = new Map();
+    for (const raiz of filhos.keys()) {
+        if (estado.has(raiz))
+            continue;
+        estado.set(raiz, 'aberto');
+        const pilha = [[raiz, 0]];
+        while (pilha.length) {
+            const topo = pilha[pilha.length - 1], lista = filhos.get(topo[0]) ?? [];
+            if (topo[1] === lista.length) {
+                estado.set(topo[0], 'fechado');
+                pilha.pop();
+                continue;
+            }
+            const filho = lista[topo[1]++], visto = estado.get(filho);
+            if (visto === 'aberto')
+                return false;
+            if (!visto) {
+                estado.set(filho, 'aberto');
+                pilha.push([filho, 0]);
+            }
+        }
+    }
+    return true;
+}
+function semantica(g) {
+    const s = g.snapshot;
+    if ((s.revision === null) === (s.revision_unavailable_reason === null))
+        falha('grafo.snapshot.revisao-inconsistente', 'snapshot');
+    const c = { snapshotId: s.snapshot_id, tenantId: g.tenant_id, manifesto: new Map(), extratores: new Set() };
+    const normalizados = new Set();
+    s.source_manifest.forEach((m, i) => {
+        const onde = `snapshot.source_manifest.${i}`;
+        if (!caminhoValido(m.path))
+            falha('grafo.caminho.invalido', onde);
+        if (c.manifesto.has(m.path))
+            falha('grafo.manifesto.duplicado', onde);
+        // NFC e NFD sao caminhos distintos aqui, mas um sistema de arquivos que normaliza os fundiria.
+        const normalizado = m.path.normalize('NFC');
+        if (normalizados.has(normalizado))
+            falha('grafo.manifesto.caminho-ambiguo', onde);
+        normalizados.add(normalizado);
+        if (autoridadeDoIndice(m.authority))
+            falha('grafo.proveniencia.autoridade-indice', onde);
+        conferirAcesso(m.access, g.tenant_id, onde);
+        c.manifesto.set(m.path, m);
+    });
+    const idsDeExtrator = new Set();
+    s.extractors.forEach((e, i) => {
+        if (idsDeExtrator.has(e.extractor_id))
+            falha('grafo.extrator.duplicado', `snapshot.extractors.${i}`);
+        idsDeExtrator.add(e.extractor_id);
+        c.extratores.add(chaveDoExtrator(e.extractor_id, e.extractor_version));
+    });
+    const nos = new Map(), localizadores = new Set();
+    g.nodes.forEach((n, i) => {
+        const onde = `nodes.${i}`;
+        if (n.snapshot_id !== s.snapshot_id)
+            falha('grafo.snapshot.divergente', onde);
+        if (!caminhoValido(n.locator.path))
+            falha('grafo.caminho.invalido', onde);
+        if ((n.kind === 'file') !== (n.locator.fragment === null))
+            falha('grafo.no.localizador-invalido', onde);
+        if (n.locator.fragment !== null && !textoValido(n.locator.fragment))
+            falha('grafo.texto.invalido', onde);
+        const m = c.manifesto.get(n.locator.path);
+        if (!m)
+            falha('grafo.no.fonte-ausente', onde);
+        if (n.source_hash !== m.source_hash)
+            falha('grafo.no.hash-divergente', onde);
+        conferirAcesso(n.access, g.tenant_id, onde);
+        if (!contem(n.access.acl_refs, m.access.acl_refs))
+            falha('grafo.acesso.restricao-omitida', onde);
+        const localizador = canonico([n.kind, n.locator]);
+        if (nos.has(n.node_id) || localizadores.has(localizador))
+            falha('grafo.no.duplicado', onde);
+        nos.set(n.node_id, n);
+        localizadores.add(localizador);
+    });
+    const arestas = new Set(), triplas = new Set(), contidos = new Map(), pais = new Set();
+    const textosDePagina = new Map();
+    g.edges.forEach((a, i) => {
+        const onde = `edges.${i}`;
+        if (a.snapshot_id !== s.snapshot_id)
+            falha('grafo.snapshot.divergente', onde);
+        const de = nos.get(a.from), para = nos.get(a.to);
+        if (!de || !para)
+            falha('grafo.aresta.endpoint-ausente', onde);
+        if (!exports.MATRIZ_DE_ARESTAS[a.kind][de.kind].includes(para.kind))
+            falha('grafo.aresta.kind-incompativel', onde);
+        // Hierarquia e declaracao moram dentro de um arquivo; a relacao entre arquivos e imports ou references.
+        if ((a.kind === 'contains' || a.kind === 'declares') && de.locator.path !== para.locator.path)
+            falha('grafo.aresta.fora-do-arquivo', onde);
+        // D5: conjuncao das restricoes das extremidades e das evidencias, nunca uniao de permissoes.
+        const exigidas = new Set([...de.access.acl_refs, ...para.access.acl_refs]), vistas = new Set();
+        a.evidence.forEach((e, j) => {
+            const ondeDaEvidencia = `${onde}.evidence.${j}`;
+            conferirEvidencia(e, c, ondeDaEvidencia);
+            if (e.span.type === 'pdf-text') {
+                // A mesma pagina da mesma fonte tem um texto extraido so; dois hashes nao podem valer juntos.
+                const pagina = canonico([e.path, e.span.page]), anterior = textosDePagina.get(pagina);
+                if (anterior !== undefined && anterior !== e.span.extracted_text_hash)
+                    falha('grafo.span.texto-da-pagina-divergente', ondeDaEvidencia);
+                textosDePagina.set(pagina, e.span.extracted_text_hash);
+            }
+            const chave = canonico(e);
+            if (vistas.has(chave))
+                falha('grafo.proveniencia.evidencia-duplicada', ondeDaEvidencia);
+            vistas.add(chave);
+            e.access.acl_refs.forEach((r) => exigidas.add(r));
+        });
+        // A relacao e observada na fonte de onde ela parte: sem evidencia la, a aresta nao e localizavel.
+        if (!a.evidence.some((e) => e.path === de.locator.path))
+            falha('grafo.proveniencia.origem-fora-do-endpoint', onde);
+        conferirAcesso(a.access, g.tenant_id, onde);
+        if (!contem(a.access.acl_refs, exigidas))
+            falha('grafo.acesso.restricao-omitida', onde);
+        const tripla = canonico([a.kind, a.from, a.to]);
+        if (arestas.has(a.edge_id) || triplas.has(tripla))
+            falha('grafo.aresta.duplicada', onde);
+        arestas.add(a.edge_id);
+        triplas.add(tripla);
+        if (a.kind === 'contains') {
+            // Depois da duplicata: a mesma aresta repetida e duplicata, nao um segundo pai.
+            if (pais.has(a.to))
+                falha('grafo.aresta.contains-com-dois-pais', onde);
+            pais.add(a.to);
+            const lista = contidos.get(a.from) ?? [];
+            lista.push(a.to);
+            contidos.set(a.from, lista);
+        }
+    });
+    if (!semCiclo(contidos))
+        falha('grafo.aresta.ciclo-contains');
+    const diagnosticos = new Set();
+    g.diagnostics.forEach((d, i) => {
+        const onde = `diagnostics.${i}`;
+        if (!caminhoValido(d.path))
+            falha('grafo.caminho.invalido', onde);
+        if (d.reference !== null && !textoValido(d.reference))
+            falha('grafo.texto.invalido', onde);
+        const m = c.manifesto.get(d.path);
+        if (!m)
+            falha('grafo.diagnostico.fonte-ausente', onde);
+        if (!c.extratores.has(chaveDoExtrator(d.extractor_id, d.extractor_version)))
+            falha('grafo.proveniencia.extrator-nao-fixado', onde);
+        conferirAcesso(d.access, g.tenant_id, onde);
+        if (!contem(d.access.acl_refs, m.access.acl_refs))
+            falha('grafo.acesso.restricao-omitida', onde);
+        const chave = canonico(d);
+        if (diagnosticos.has(chave))
+            falha('grafo.diagnostico.duplicado', onde);
+        diagnosticos.add(chave);
+    });
+    // D2: id fornecido pelo produtor e recalculado; divergencia e recusa, nunca correcao silenciosa.
+    if (s.extractors_digest !== (0, exports.digestDosExtratores)(s.extractors) || s.snapshot_id !== idDoSnapshot(g))
+        falha('grafo.id.divergente', 'snapshot');
+    g.nodes.forEach((n, i) => {
+        if (n.node_id !== idDoNo(g.tenant_id, g.repository_id, s.snapshot_id, n.kind, n.locator))
+            falha('grafo.id.divergente', `nodes.${i}`);
+    });
+    g.edges.forEach((a, i) => {
+        if (a.edge_id !== idDaAresta(a))
+            falha('grafo.id.divergente', `edges.${i}`);
+    });
+}
+/**
+ * Validacao estrutural e semantica pura. Devolve o grafo na forma canonica (conjuntos ordenados)
+ * ou lanca erro com codigo `grafo.*`. Sem fontes, a evidencia so e conferida na estrutura.
+ */
+function validarGrafo(entrada) {
+    if (entrada !== null && typeof entrada === 'object' && !Array.isArray(entrada) && 'schema' in entrada &&
+        entrada.schema !== exports.GRAFO_SCHEMA)
+        falha('grafo.versao.incompativel');
+    const r = exports.grafoSchema.safeParse(entrada);
+    if (!r.success)
+        falha('grafo.estrutura.invalida', r.error.issues[0]?.path.join('.') || 'raiz');
+    semantica(r.data);
+    return canonizar(r.data);
+}
+/** D2: digest canonico do grafo valido; permutar nos, arestas ou evidencias nao o muda. */
+const digestDoGrafo = (entrada) => (0, exports.sha256DoCanonico)(validarGrafo(entrada));
+exports.digestDoGrafo = digestDoGrafo;
+function utf8Valido(b) {
+    try {
+        new TextDecoder('utf-8', { fatal: true }).decode(b);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const fronteiraUtf8 = (b, i) => i === b.length || (i < b.length && (b[i] & 0xc0) !== 0x80);
+function quebrasDeLinha(b) {
+    const q = [];
+    for (let i = 0; i < b.length; i++)
+        if (b[i] === 0x0a)
+            q.push(i);
+    return q;
+}
+/** Linha (1-based) do byte `o`: uma a mais que as quebras antes dele. */
+function linhaDoByte(quebras, o) {
+    let baixo = 0, alto = quebras.length;
+    while (baixo < alto) {
+        const meio = (baixo + alto) >> 1;
+        if (quebras[meio] < o)
+            baixo = meio + 1;
+        else
+            alto = meio;
+    }
+    return baixo + 1;
+}
+/**
+ * D4: confere hash, tamanho e spans contra bytes fornecidos. Acerto de span nao prova que o
+ * parser interpretou a relacao certo; essa prova vem da auditoria de arestas do benchmark.
+ */
+function conferirFontes(entrada, fontes) {
+    const g = validarGrafo(entrada);
+    const manifesto = new Map(g.snapshot.source_manifest.map((m) => [m.path, m]));
+    for (const [p, f] of fontes) {
+        if (!manifesto.has(p))
+            falha('grafo.fonte.fora-do-manifesto');
+        const tipo = f !== null && typeof f === 'object' ? f.tipo : undefined;
+        if (!['texto', 'binario', 'pdf'].includes(tipo))
+            falha('grafo.fonte.tipo-desconhecido');
+        if (!(f.bytes instanceof Uint8Array) || (f.tipo === 'pdf' && !(Array.isArray(f.paginas) && f.paginas.every((x) => x instanceof Uint8Array)))) {
+            falha('grafo.fonte.incompleta');
+        }
+    }
+    const fontesVerificadas = [], fontesIndisponiveis = [];
+    g.snapshot.source_manifest.forEach((m, i) => {
+        const onde = `snapshot.source_manifest.${i}`, f = fontes.get(m.path);
+        if (!f) {
+            fontesIndisponiveis.push(m.path);
+            return;
+        }
+        if (f.bytes.length !== m.size_bytes)
+            falha('grafo.fonte.tamanho-divergente', onde);
+        if (sha256DosBytes(f.bytes) !== m.source_hash)
+            falha('grafo.fonte.hash-divergente', onde);
+        const textos = f.tipo === 'texto' ? [f.bytes] : f.tipo === 'pdf' ? f.paginas : [];
+        if (!textos.every(utf8Valido))
+            falha('grafo.fonte.utf8-invalido', onde);
+        fontesVerificadas.push(m.path);
+    });
+    const quebras = new Map();
+    let evidenciasVerificadas = 0, evidenciasIndisponiveis = 0;
+    g.edges.forEach((a, i) => a.evidence.forEach((e, j) => {
+        const onde = `edges.${i}.evidence.${j}`, f = fontes.get(e.path), s = e.span;
+        if (!f) {
+            evidenciasIndisponiveis++;
+            return;
+        }
+        let texto;
+        if (s.type === 'text') {
+            if (f.tipo !== 'texto')
+                falha('grafo.span.tipo-incompativel', onde);
+            texto = f.bytes;
+        }
+        else {
+            if (f.tipo !== 'pdf')
+                falha('grafo.span.tipo-incompativel', onde);
+            if (s.page > f.paginas.length)
+                falha('grafo.span.pagina-inexistente', onde);
+            texto = f.paginas[s.page - 1];
+            if (sha256DosBytes(texto) !== s.extracted_text_hash)
+                falha('grafo.span.texto-da-pagina-divergente', onde);
+        }
+        if (s.byte_end > texto.length)
+            falha('grafo.span.fora-da-fonte', onde);
+        if (!fronteiraUtf8(texto, s.byte_start) || !fronteiraUtf8(texto, s.byte_end))
+            falha('grafo.span.fronteira-utf8', onde);
+        if (s.type === 'text' && s.line_start !== null) {
+            const q = quebras.get(e.path) ?? quebrasDeLinha(texto);
+            quebras.set(e.path, q);
+            if (linhaDoByte(q, s.byte_start) !== s.line_start || linhaDoByte(q, s.byte_end - 1) !== s.line_end) {
+                falha('grafo.span.linhas-divergentes', onde);
+            }
+        }
+        evidenciasVerificadas++;
+    }));
+    const completa = fontesIndisponiveis.length === 0 && evidenciasIndisponiveis === 0;
+    return { estado: completa ? 'verificada' : 'parcial', fontesVerificadas, fontesIndisponiveis, evidenciasVerificadas, evidenciasIndisponiveis };
+}