@orkastery/cli 0.5.3 → 0.6.0

package/dist/conhecimento.js

@@ -0,0 +1,514 @@
+"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.compararLacunas = exports.detalheDoConhecimento = exports.LIMITES_DO_CONHECIMENTO = exports.REFERENCIA_DE_DECISAO = exports.NOME_DE_COLECAO = exports.ID_DE_DOCUMENTO = exports.CONTRATO_CONHECIMENTO = void 0;
+exports.lacunaDoConhecimento = lacunaDoConhecimento;
+exports.lerConhecimento = lerConhecimento;
+/**
+ * RM-026 K7 (fatia 1): conhecimento escrito, no contrato `ork.conhecimento/v1`.
+ *
+ * Cada documento é um Markdown versionado na pasta que o `orkastery.yaml` declara (`conhecimento.dir`), com
+ * frontmatter fechado: `id` (`doc-...`), `titulo`, `colecoes` e, opcional, `referencias` a ids do Brain e a
+ * decisões `thread#linha` do ledger. A coleção é o nome no frontmatter, sem arquivo próprio.
+ *
+ * Só leitura. Documento inválido ou referência que não confere vira lacuna tipada, nunca resposta (D4). A pasta
+ * vem com o repositório e segue a fronteira da RM-047 (D6): relativa, dentro da raiz pelo caminho real, sem
+ * seguir link e sem executar nada. O leitor confere a decisão no ledger canônico e o id do Brain só pela forma
+ * (D5); a conferência por `get` mora na consulta (`conhecimento-consulta.ts`, fatia 2), a porta pública da CLI e das
+ * tools MCP. O detalhe das lacunas sai pelo catálogo (família `conhecimento`). Contrato:
+ * docs/referencia/contratos/conhecimento-rm026.md.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_buffer_1 = require("node:buffer");
+const company_brain_journal_1 = require("./company-brain-journal");
+const docs_1 = require("./docs");
+const locale_1 = require("./locale");
+const portfolio_1 = require("./portfolio");
+const saida_segura_1 = require("./saida-segura");
+const thread_1 = require("./thread");
+const yaml_1 = require("./yaml");
+exports.CONTRATO_CONHECIMENTO = 'ork.conhecimento/v1';
+/** D3: a forma do id do documento (a regra dos ids do portfólio), da coleção e da citação de decisão. */
+exports.ID_DE_DOCUMENTO = /^doc-[a-z0-9][a-z0-9-]{2,47}$/;
+exports.NOME_DE_COLECAO = /^[a-z0-9][a-z0-9-]{0,47}$/;
+exports.REFERENCIA_DE_DECISAO = /^([a-zA-Z0-9][a-zA-Z0-9._-]{0,79})#([1-9][0-9]{0,8})$/;
+const LIMITE_DO_TITULO = 160;
+const COLECOES_POR_DOCUMENTO = 16;
+const REFERENCIAS_POR_LISTA = 64;
+/** D2: as chaves do frontmatter; qualquer outra invalida o documento. */
+const CHAVES_DO_DOCUMENTO = ['id', 'titulo', 'colecoes', 'referencias'];
+const CHAVES_DAS_REFERENCIAS = ['brain', 'decisoes'];
+/** D5: as linhas do ledger que são decisão, as do dossiê; `human_decision` é relato sem recibo e não conta. */
+const TIPOS_DE_DECISAO = ['autonomous_decision', 'hitl_requested', 'human_gate'];
+/** D6: pastas do repositório que nunca guardam conhecimento, sem distinguir caixa (o disco do macOS não distingue). */
+const PASTAS_RESERVADAS = ['.git', '.orkastery'];
+const reservada = (segmento) => PASTAS_RESERVADAS.includes(segmento.toLowerCase());
+/** D10: o invisível é o do `saida-segura.ts`, a regra única do núcleo para texto alheio (ZWJ e seletores de emoji valem). */
+const INVISIVEIS = new RegExp(saida_segura_1.INVISIVEL.source, 'gu');
+exports.LIMITES_DO_CONHECIMENTO = Object.freeze({
+    entradas: 5000, profundidade: 8, bytesPorDocumento: 1024 * 1024, bytesDoFrontmatter: 16 * 1024,
+    bytesNoTotal: 32 * 1024 * 1024, bytesDoLedger: 16 * 1024 * 1024, bytesDosLedgers: 64 * 1024 * 1024,
+    getsDoBrain: 100, msDaConferencia: 60 * 1000,
+});
+const comparar = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+const ehMapa = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/** Texto que veio do repositório, pronto para a resposta: numa linha, sem invisível e, com teto, cortado sem partir caractere. */
+const limpo = (v, teto = Infinity) => Array.from((0, saida_segura_1.emUmaLinha)(v)).slice(0, teto).join('');
+const relativo = (raizReal, abs) => path.relative(raizReal, abs).split(path.sep).join('/');
+/**
+ * O detalhe de uma lacuna, pelo catálogo (D13 da fatia 2): nasce no locale ativo, o pt-BR do `--json` e do MCP, e a
+ * impressão do comando coberto o remonta no locale dela.
+ */
+const detalheDoConhecimento = (montar) => (0, locale_1.textoDoCatalogo)((m) => montar(m.conhecimento.lacunas));
+exports.detalheDoConhecimento = detalheDoConhecimento;
+const t = exports.detalheDoConhecimento;
+/** `stat` que nunca lança: a pasta que some ou não abre vale como ausente. */
+const statOuNulo = (p) => { try {
+    return fs.statSync(p, { throwIfNoEntry: false }) ?? null;
+}
+catch {
+    return null;
+} };
+/** Uma lacuna, com a referência como escrita, numa linha e cortada (a mesma regra no leitor e na consulta). */
+function lacunaDoConhecimento(codigo, detalhe, onde = {}) {
+    return { codigo, arquivo: onde.arquivo ?? null, documento: onde.documento ?? null,
+        referencia: typeof onde.referencia === 'string' ? limpo(onde.referencia, 200) : null, detalhe };
+}
+const lacuna = lacunaDoConhecimento;
+/** A ordem estável das lacunas: por arquivo, código e referência. */
+const compararLacunas = (a, b) => comparar(a.arquivo ?? '', b.arquivo ?? '') || comparar(a.codigo, b.codigo) || comparar(a.referencia ?? '', b.referencia ?? '');
+exports.compararLacunas = compararLacunas;
+/**
+ * D6: a pasta declarada, pelo caminho real. A forma recusa antes de tocar o disco (vazia, absoluta, `..`, `\`,
+ * invisível, a própria raiz, `.git` e `.orkastery`); o caminho real, com os links resolvidos, precisa ficar dentro
+ * da raiz.
+ */
+function pastaDoConhecimento(raiz, dir) {
+    const segmentos = dir.split('/').filter((s) => s !== '' && s !== '.');
+    if (path.isAbsolute(dir) || dir.includes('\\') || saida_segura_1.INVISIVEL.test(dir) || !segmentos.length || segmentos.includes('..') ||
+        reservada(segmentos[0])) {
+        return lacuna('conhecimento.dir-invalido', t((l) => l.dirForma));
+    }
+    let raizReal, real;
+    try {
+        raizReal = fs.realpathSync(raiz);
+        real = fs.realpathSync(path.join(raizReal, ...segmentos));
+    }
+    catch {
+        return lacuna('conhecimento.dir-ausente', t((l) => l.dirNaoAbre));
+    }
+    const rel = path.relative(raizReal, real);
+    if (rel === '..' || rel.startsWith('..' + path.sep) || path.isAbsolute(rel)) {
+        return lacuna('conhecimento.dir-fora-da-raiz', t((l) => l.dirForaDaRaiz));
+    }
+    if (rel === '' || reservada(rel.split(path.sep)[0]) || saida_segura_1.INVISIVEL.test(rel)) {
+        return lacuna('conhecimento.dir-invalido', t((l) => l.dirReal));
+    }
+    if (!statOuNulo(real)?.isDirectory())
+        return lacuna('conhecimento.dir-ausente', t((l) => l.dirNaoEPasta));
+    return { real, raizReal };
+}
+/**
+ * Varre a pasta sem seguir link (D6) e sem ler entrada oculta (D8). Devolve os candidatos a documento, ou o
+ * detalhe do teto estourado (D7), que falha fechado. Entrada que não abre vira lacuna, nunca exceção.
+ */
+function varrer(real, raizReal, limites, lacunas) {
+    const candidatos = [];
+    const pilha = [{ abs: real, profundidade: 0 }];
+    let entradas = 0;
+    while (pilha.length) {
+        const atual = pilha.pop();
+        // Uma pasta trocada por link depois de entrar na pilha não leva a varredura para fora: o caminho real é
+        // conferido logo antes da listagem. Num clone parado não há troca; a conferência fecha a janela larga.
+        let realDaPasta;
+        try {
+            realDaPasta = fs.realpathSync(atual.abs);
+        }
+        catch {
+            realDaPasta = null;
+        }
+        if (realDaPasta !== atual.abs) {
+            lacunas.push(lacuna('documento.link', t((l) => l.link), { arquivo: relativo(raizReal, atual.abs) }));
+            continue;
+        }
+        let nomes;
+        try {
+            nomes = fs.readdirSync(atual.abs, { encoding: 'buffer' }).sort(Buffer.compare);
+        }
+        catch {
+            lacunas.push(lacuna('documento.nao-regular', t((l) => l.pastaNaoAbriu), { arquivo: relativo(raizReal, atual.abs) }));
+            continue;
+        }
+        for (const bruto of nomes) {
+            if (bruto[0] === 0x2e)
+                continue;
+            if (++entradas > limites.entradas)
+                return { teto: t((l) => l.limiteEntradas(limites.entradas)) };
+            const nome = bruto.toString('utf8');
+            if (!Buffer.from(nome, 'utf8').equals(bruto) || saida_segura_1.INVISIVEL.test(nome)) {
+                lacunas.push(lacuna('documento.nome-invalido', t((l) => l.nomeInvalido), { arquivo: relativo(raizReal, path.join(atual.abs, nome.replace(INVISIVEIS, '?'))) }));
+                continue;
+            }
+            const abs = path.join(atual.abs, nome), arquivo = relativo(raizReal, abs);
+            let st;
+            try {
+                st = fs.lstatSync(abs, { throwIfNoEntry: false });
+            }
+            catch {
+                lacunas.push(lacuna('documento.nao-regular', t((l) => l.entradaNaoAbriu), { arquivo }));
+                continue;
+            }
+            if (!st)
+                continue;
+            if (st.isSymbolicLink()) {
+                lacunas.push(lacuna('documento.link', t((l) => l.link), { arquivo }));
+                continue;
+            }
+            if (st.isDirectory()) {
+                if (atual.profundidade + 1 > limites.profundidade)
+                    return { teto: t((l) => l.limiteNiveis(limites.profundidade)) };
+                pilha.push({ abs, profundidade: atual.profundidade + 1 });
+                continue;
+            }
+            if (!(0, docs_1.ehPaginaDeDocs)(nome))
+                continue;
+            if (!st.isFile()) {
+                lacunas.push(lacuna('documento.nao-regular', t((l) => l.naoRegular), { arquivo }));
+                continue;
+            }
+            candidatos.push({ abs, arquivo, st });
+        }
+    }
+    return candidatos;
+}
+/**
+ * Lê um arquivo comum sem seguir link (`O_NOFOLLOW`) e sem travar em FIFO (`O_NONBLOCK`), conferindo que é o
+ * mesmo do `lstat` e que cabe no teto. Devolve os bytes ou o motivo. Com `crescer` (o ledger, que só recebe linha
+ * no fim), vale o que existia no `fstat`, mesmo que o arquivo cresça durante a leitura; o documento que muda
+ * durante a leitura não vale.
+ */
+function lerArquivo(abs, st, teto, crescer = false) {
+    let fd;
+    try {
+        fd = fs.openSync(abs, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    }
+    catch (e) {
+        return e.code === 'ELOOP' ? 'link' : 'nao-regular';
+    }
+    try {
+        const f = fs.fstatSync(fd);
+        if (!f.isFile() || f.dev !== st.dev || f.ino !== st.ino)
+            return 'nao-regular';
+        if (f.size > teto)
+            return 'grande';
+        const bytes = Buffer.alloc(crescer ? f.size : f.size + 1);
+        let lidos = 0, n;
+        while (lidos < bytes.length && (n = fs.readSync(fd, bytes, lidos, bytes.length - lidos, null)) > 0)
+            lidos += n;
+        if (crescer)
+            return bytes.subarray(0, lidos);
+        return lidos === f.size ? bytes.subarray(0, lidos) : 'nao-regular';
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * Valor de lista do frontmatter: lista de textos ou um texto só. Inteiro vira texto, sem perda; nulo, booleano
+ * e decimal (o `yes` que o YAML lê como `true`, a vírgula sobrando que vira nulo) recusam em vez de virar texto.
+ */
+function lista(v) {
+    if (v === undefined || v === null)
+        return [];
+    const itens = [];
+    for (const b of Array.isArray(v) ? v : [v]) {
+        if (typeof b === 'string')
+            itens.push(b);
+        else if (typeof b === 'number' && Number.isSafeInteger(b))
+            itens.push(String(b));
+        else
+            return null;
+    }
+    return itens;
+}
+/** D2 e D3: o frontmatter vale inteiro ou devolve a lacuna do primeiro problema, com o id quando ele já vale. */
+function validarFrontmatter(dados, arquivo) {
+    if (!ehMapa(dados))
+        return lacuna('documento.frontmatter-invalido', t((l) => l.frontmatterNaoEMapa), { arquivo });
+    const id = typeof dados.id === 'string' && exports.ID_DE_DOCUMENTO.test(dados.id) ? dados.id : null;
+    if (!id)
+        return lacuna('documento.id-invalido', t((l) => l.idInvalido), { arquivo });
+    const onde = { arquivo, documento: id };
+    const estranhas = Object.keys(dados).filter((k) => !CHAVES_DO_DOCUMENTO.includes(k));
+    if (estranhas.length) {
+        const chaves = estranhas.map((k) => JSON.stringify(limpo(k, 40))).join(', ');
+        return lacuna('documento.chave-desconhecida', t((l) => l.chaveDesconhecida(chaves, CHAVES_DO_DOCUMENTO.join(', '))), onde);
+    }
+    const titulo = typeof dados.titulo === 'string' ? dados.titulo.trim() : '';
+    if (!titulo || titulo.length > LIMITE_DO_TITULO || saida_segura_1.INVISIVEL.test(titulo)) {
+        return lacuna('documento.titulo-invalido', t((l) => l.tituloInvalido(LIMITE_DO_TITULO)), onde);
+    }
+    const colecoes = lista(dados.colecoes);
+    if (!colecoes || !colecoes.length || colecoes.length > COLECOES_POR_DOCUMENTO ||
+        colecoes.some((c) => !exports.NOME_DE_COLECAO.test(c)) || new Set(colecoes).size !== colecoes.length) {
+        return lacuna('documento.colecoes-invalidas', t((l) => l.colecoesInvalidas(COLECOES_POR_DOCUMENTO)), onde);
+    }
+    const refs = dados.referencias ?? null;
+    const brain = ehMapa(refs) ? lista(refs.brain) : [], decisoes = ehMapa(refs) ? lista(refs.decisoes) : [];
+    if ((refs !== null && !ehMapa(refs)) || (ehMapa(refs) && Object.keys(refs).some((k) => !CHAVES_DAS_REFERENCIAS.includes(k))) ||
+        !brain || brain.length > REFERENCIAS_POR_LISTA || !decisoes || decisoes.length > REFERENCIAS_POR_LISTA) {
+        return lacuna('documento.referencias-invalidas', t((l) => l.referenciasInvalidas(REFERENCIAS_POR_LISTA)), onde);
+    }
+    return { id, titulo, colecoes: [...colecoes].sort(comparar), brain: [...new Set(brain)], decisoes: [...new Set(decisoes)] };
+}
+/**
+ * As linhas citadas do ledger canônico de uma thread (D5). O ledger é lido como a captura do Brain o lê
+ * (`readCycle`): só linhas completas, em UTF-8 exato, para o sha256 da linha ser o `source_hash` dela no Brain.
+ * Cada ledger é lido uma vez, até a maior linha citada, e só as linhas citadas viram texto (fatia 2: a leitura não parte
+ * o ledger inteiro em linhas). `completas` é exato quando alguma linha citada passa do fim, o único caso em que ele é
+ * dito. O `orcamento` é o que resta do teto de bytes dos ledgers da leitura.
+ */
+function linhasCitadas(raiz, thread, citadas, limites, orcamento) {
+    let arquivo;
+    try {
+        arquivo = path.join((0, thread_1.dirThread)(raiz, thread), 'ledger.jsonl');
+    }
+    catch {
+        return { motivo: t((l) => l.ledgerLinkOuId) };
+    }
+    let st;
+    try {
+        st = fs.lstatSync(arquivo, { throwIfNoEntry: false });
+    }
+    catch (e) {
+        // A pasta da thread que é arquivo comum dá ENOTDIR: a thread não tem ledger, e nada lança.
+        if (e.code !== 'ENOTDIR')
+            return { motivo: t((l) => l.ledgerNaoAbriu(thread)) };
+    }
+    if (!st)
+        return { motivo: t((l) => l.semLedger(thread)) };
+    if (st.size > orcamento.restante)
+        return { motivo: t((l) => l.ledgersDemais(limites.bytesDosLedgers / 1024 / 1024)) };
+    const bytes = lerArquivo(arquivo, st, limites.bytesDoLedger, true);
+    if (!Buffer.isBuffer(bytes))
+        return { motivo: t((l) => l.ledgerNaoRegular(thread, limites.bytesDoLedger / 1024 / 1024)) };
+    orcamento.restante -= bytes.length;
+    const completo = bytes.subarray(0, bytes.lastIndexOf(10) + 1);
+    if (!(0, node_buffer_1.isUtf8)(completo))
+        return { motivo: t((l) => l.ledgerNaoUtf8(thread)) };
+    let maior = 0;
+    for (const n of citadas)
+        if (n > maior)
+            maior = n;
+    const linhas = new Map();
+    let inicio = 0, n = 0;
+    while (inicio < completo.length && n < maior) {
+        const fimDaLinha = completo.indexOf(10, inicio);
+        n++;
+        if (citadas.has(n))
+            linhas.set(n, completo.subarray(inicio, fimDaLinha).toString('utf8'));
+        inicio = fimDaLinha + 1;
+    }
+    return { linhas, completas: n };
+}
+/** D5: a referência `thread#linha` confere quando a linha completa existe, é da thread e é uma decisão. */
+function conferirDecisao(ref, ledgers) {
+    const m = exports.REFERENCIA_DE_DECISAO.exec(ref);
+    if (!m)
+        return { codigo: 'referencia.invalida', detalhe: t((l) => l.decisaoForma) };
+    const thread = m[1], linha = Number(m[2]);
+    const ledger = ledgers.get(thread);
+    if ('motivo' in ledger)
+        return { codigo: 'referencia.decisao-ausente', detalhe: ledger.motivo };
+    const bruta = ledger.linhas.get(linha);
+    if (bruta === undefined) {
+        return { codigo: 'referencia.decisao-ausente', detalhe: t((l) => l.linhasCompletas(thread, ledger.completas)) };
+    }
+    let evento = null;
+    try {
+        const lido = JSON.parse(bruta);
+        if (lido && typeof lido === 'object' && !Array.isArray(lido))
+            evento = lido;
+    }
+    catch { /* linha que não é JSON não é decisão */ }
+    if (!evento)
+        return { codigo: 'referencia.nao-e-decisao', detalhe: t((l) => l.naoEJson(linha, thread)) };
+    if (evento.thread !== thread)
+        return { codigo: 'referencia.nao-e-decisao', detalhe: t((l) => l.outraThread(linha, thread)) };
+    const tipo = TIPOS_DE_DECISAO.find((x) => x === evento?.tipo);
+    if (!tipo) {
+        const visto = typeof evento.tipo === 'string' && /^[a-z_]{1,40}$/.test(evento.tipo) ? evento.tipo : null;
+        return { codigo: 'referencia.nao-e-decisao', detalhe: t((l) => l.naoEDecisao(linha, thread, visto, TIPOS_DE_DECISAO.join(', '))) };
+    }
+    return { ref, thread, linha, tipo, fonte: `threads/${thread}/ledger.jsonl#L${linha}`, sha256: (0, company_brain_journal_1.bytesHash)(bruta) };
+}
+/**
+ * Lê o conhecimento declarado no manifesto: documentos válidos, coleções e lacunas, tudo em ordem estável.
+ * Nunca lança por causa do conteúdo do repositório; o que não vale vira lacuna tipada.
+ */
+function lerConhecimento(c, limites = exports.LIMITES_DO_CONHECIMENTO, opcoes = {}) {
+    const declarado = c.manifesto.conhecimento?.dir ?? null;
+    const dir = declarado === null ? null : limpo(declarado);
+    const so = (l) => ({ contrato: exports.CONTRATO_CONHECIMENTO, dir, documentos: [], colecoes: [], lacunas: [l] });
+    if (declarado === null)
+        return so(lacuna('conhecimento.nao-declarado', t((l) => l.naoDeclarado)));
+    const pasta = pastaDoConhecimento(c.raiz, declarado);
+    if ('codigo' in pasta)
+        return so(pasta);
+    const teto = (detalhe) => so(lacuna('conhecimento.limite', detalhe));
+    const lacunas = [];
+    const candidatos = varrer(pasta.real, pasta.raizReal, limites, lacunas);
+    if (!Array.isArray(candidatos))
+        return teto(candidatos.teto);
+    const decodificador = new TextDecoder('utf-8', { fatal: true });
+    const validos = [];
+    const declarados = new Map();
+    let total = 0;
+    for (const { abs, arquivo, st } of candidatos) {
+        const bytes = lerArquivo(abs, st, limites.bytesPorDocumento);
+        if (bytes === 'link') {
+            lacunas.push(lacuna('documento.link', t((l) => l.link), { arquivo }));
+            continue;
+        }
+        if (bytes === 'nao-regular') {
+            lacunas.push(lacuna('documento.nao-regular', t((l) => l.naoAbriuComoArquivo), { arquivo }));
+            continue;
+        }
+        if (bytes === 'grande') {
+            lacunas.push(lacuna('documento.grande-demais', t((l) => l.grandeDemais(limites.bytesPorDocumento / 1024)), { arquivo }));
+            continue;
+        }
+        total += bytes.length;
+        if (total > limites.bytesNoTotal)
+            return teto(t((l) => l.limiteTotal(limites.bytesNoTotal / 1024 / 1024)));
+        let texto;
+        try {
+            texto = decodificador.decode(bytes);
+        }
+        catch {
+            lacunas.push(lacuna('documento.codificacao', t((l) => l.codificacao), { arquivo }));
+            continue;
+        }
+        const { bruto, corpo } = (0, docs_1.separarFrontmatter)(texto);
+        if (bruto === null) {
+            lacunas.push(lacuna('documento.sem-frontmatter', t((l) => l.semFrontmatter), { arquivo }));
+            continue;
+        }
+        if (Buffer.byteLength(bruto, 'utf8') > limites.bytesDoFrontmatter) {
+            lacunas.push(lacuna('documento.frontmatter-invalido', t((l) => l.frontmatterGrande(limites.bytesDoFrontmatter / 1024)), { arquivo }));
+            continue;
+        }
+        let dados;
+        // A linha do `---` de abertura entra na leitura (e é pulada nela) para o erro dizer a linha do arquivo.
+        try {
+            dados = (0, yaml_1.lerYaml)('---\n' + bruto, { estrito: true });
+        }
+        catch (e) {
+            const erro = limpo(e.message, 200);
+            lacunas.push(lacuna('documento.frontmatter-invalido', t((l) => l.frontmatterYaml(erro)), { arquivo }));
+            continue;
+        }
+        // D4: o id na forma certa conta para a regra do repetido mesmo quando o resto do documento não vale.
+        const idDeclarado = ehMapa(dados) && typeof dados.id === 'string' && exports.ID_DE_DOCUMENTO.test(dados.id) ? dados.id : null;
+        if (idDeclarado)
+            declarados.set(idDeclarado, (declarados.get(idDeclarado) ?? 0) + 1);
+        const v = validarFrontmatter(dados, arquivo);
+        if ('codigo' in v) {
+            lacunas.push(v);
+            continue;
+        }
+        validos.push({ ...v, arquivo, bytes: bytes.length, sha256: (0, company_brain_journal_1.bytesHash)(bytes), ...(v.id === opcoes.corpoDe ? { corpo } : {}) });
+    }
+    // D4: id repetido não escolhe arquivo; todos os documentos com ele saem da resposta, também quando a outra
+    // cópia não vale por outro motivo (ela já tem a lacuna dela).
+    const unicos = validos.filter((v) => {
+        const vezes = declarados.get(v.id);
+        if (vezes > 1) {
+            lacunas.push(lacuna('documento.id-repetido', t((l) => l.idRepetido(vezes)), { arquivo: v.arquivo, documento: v.id }));
+        }
+        return vezes === 1;
+    });
+    // D5: cada ledger citado é lido uma vez, com as linhas que os documentos válidos pedem, em ordem de thread e até o
+    // teto de bytes da leitura. Fatia 2: só os documentos cujas decisões a consulta mostra (`decisoesDe`).
+    const decisoesDe = opcoes.decisoesDe ?? 'todos';
+    const confere = (id) => decisoesDe === 'todos' || decisoesDe === id;
+    const citadas = new Map();
+    for (const v of unicos)
+        if (confere(v.id))
+            for (const ref of v.decisoes) {
+                const m = exports.REFERENCIA_DE_DECISAO.exec(ref);
+                if (m)
+                    citadas.set(m[1], (citadas.get(m[1]) ?? new Set()).add(Number(m[2])));
+            }
+    const ledgers = new Map(), orcamento = { restante: limites.bytesDosLedgers };
+    for (const thread of [...citadas.keys()].sort(comparar)) {
+        ledgers.set(thread, linhasCitadas(c.raiz, thread, citadas.get(thread), limites, orcamento));
+    }
+    const documentos = [];
+    for (const v of unicos) {
+        const onde = { arquivo: v.arquivo, documento: v.id };
+        const brain = [], decisoes = [];
+        for (const referencia of v.brain) {
+            if (portfolio_1.ID_DE_ENTIDADE.test(referencia))
+                brain.push(referencia);
+            else
+                lacunas.push(lacuna('referencia.invalida', t((l) => l.brainForma), { ...onde, referencia }));
+        }
+        for (const referencia of confere(v.id) ? v.decisoes : []) {
+            const r = conferirDecisao(referencia, ledgers);
+            if ('codigo' in r)
+                lacunas.push(lacuna(r.codigo, r.detalhe, { ...onde, referencia }));
+            else
+                decisoes.push(r);
+        }
+        documentos.push({ id: v.id, titulo: v.titulo, colecoes: v.colecoes,
+            referencias: { brain: brain.sort(comparar), decisoes: decisoes.sort((a, b) => comparar(a.thread, b.thread) || a.linha - b.linha) },
+            arquivo: v.arquivo, bytes: v.bytes, sha256: v.sha256, ...(v.corpo !== undefined ? { corpo: v.corpo } : {}) });
+    }
+    const colecoes = new Map();
+    for (const d of documentos)
+        for (const nome of d.colecoes) {
+            const ids = colecoes.get(nome) ?? [];
+            ids.push(d.id);
+            colecoes.set(nome, ids);
+        }
+    return {
+        contrato: exports.CONTRATO_CONHECIMENTO, dir,
+        documentos: documentos.sort((a, b) => comparar(a.id, b.id)),
+        colecoes: [...colecoes].map(([nome, ids]) => ({ nome, documentos: ids.sort(comparar) })).sort((a, b) => comparar(a.nome, b.nome)),
+        lacunas: lacunas.sort(exports.compararLacunas),
+    };
+}

package/dist/conta-esgotada.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reconciliarContaEsgotada = reconciliarContaEsgotada;
+/** RM-064 T1/T2: uma cota esgotada pertence à conta, não só à sessão que a revelou. */
+const node_crypto_1 = require("node:crypto");
+const claude_bg_1 = require("./adapters/claude-bg");
+const hitl_sessions_1 = require("./hitl-sessions");
+const ledger_1 = require("./ledger");
+const projeto_alvo_1 = require("./projeto-alvo");
+const runtime_profiles_1 = require("./runtime-profiles");
+const session_events_1 = require("./session-events");
+const sessoes_inventario_1 = require("./sessoes-inventario");
+const thread_1 = require("./thread");
+const sha = (v) => (0, node_crypto_1.createHash)('sha256').update(JSON.stringify(v)).digest('hex');
+const padrao = {
+    inventario: (raiz) => (0, sessoes_inventario_1.inventariarSessoes)(raiz, { global: true, todas: true, prazoMs: 30_000 }),
+    projetos: (raiz) => [...new Set([raiz, ...(0, projeto_alvo_1.listarProjetos)().filter((p) => p.presente).map((p) => p.raiz)])],
+    parar: (sessionId, id, perfil, vinculo) => {
+        if (perfil.runtime === 'codex') {
+            if (!vinculo)
+                return { ok: false, detalhe: 'vínculo canônico do controller ausente' };
+            try {
+                const ctl = (0, hitl_sessions_1.controleNativo)('codex', vinculo.raiz, vinculo.thread, sessionId);
+                const consulta = ctl.consultar();
+                const candidatas = consulta.sessoes.filter((s) => s.sessionId === sessionId && s.runtime === 'codex');
+                if (!consulta.ok || candidatas.length !== 1)
+                    return { ok: false, detalhe: 'controller codex não confirmou identidade única' };
+                return { ok: ctl.parar(candidatas[0]), detalhe: 'controller codex vinculado recebeu interrupção' };
+            }
+            catch (e) {
+                return { ok: false, detalhe: e.message };
+            }
+        }
+        const r = (0, claude_bg_1.pararAchada)({ sessionId, ...(id ? { id } : {}) }, (0, claude_bg_1.ambienteDoPerfil)(perfil));
+        return { ok: r.ok, detalhe: r.texto || (r.ok ? 'runtime confirmou a parada' : 'runtime recusou a parada') };
+    },
+};
+function vinculosDaConta(projetos, sessionId, conta) {
+    const vinculos = [], falhas = [];
+    for (const raiz of projetos) {
+        let ids;
+        try {
+            ids = (0, thread_1.listarIds)(raiz);
+        }
+        catch (e) {
+            falhas.push(`projeto não lido: ${e.message}`);
+            continue;
+        }
+        for (const id of ids) {
+            try {
+                const thread = (0, thread_1.lerThread)(raiz, id);
+                const sessao = thread.sessoes.find((s) => s.sessionId === sessionId && s.origem !== 'adocao');
+                if (!sessao?.despachadaEm)
+                    continue;
+                const eventos = (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, id));
+                const perfil = (0, runtime_profiles_1.perfilDoRegistro)(eventos, { sessionId, despachadaEm: sessao.despachadaEm });
+                if (!perfil || (0, runtime_profiles_1.chaveDaConta)(perfil) !== conta)
+                    continue;
+                vinculos.push({ raiz, thread: id, fase: sessao.fase, despachoEm: sessao.despachadaEm });
+            }
+            catch (e) {
+                falhas.push(`vínculo ${id} não confirmado: ${e.message}`);
+            }
+        }
+    }
+    return { vinculos: vinculos.filter((v, i, a) => a.findIndex((x) => x.raiz === v.raiz && x.thread === v.thread) === i), falhas };
+}
+/**
+ * Para cada sessão viva da mesma conta: prova o vínculo pelo ledger, pede a parada uma vez e só
+ * então grava o terminal que libera a condução. Consulta incompleta nunca vira falso sucesso.
+ */
+function reconciliarContaEsgotada(entrada, deps = padrao) {
+    const agoraMs = entrada.agoraMs ?? Date.now();
+    const contaBruta = (0, runtime_profiles_1.chaveDaConta)(entrada.perfil), conta = sha(contaBruta);
+    const episodio = sha([conta, entrada.erroEm, entrada.esgotadoAte]);
+    const inv = deps.inventario(entrada.raiz);
+    const projetos = deps.projetos(entrada.raiz);
+    const falhas = inv.fontes.filter((f) => !f.ok).map((f) => f.detalhe);
+    const sessoes = [];
+    const candidatas = inv.sessoes.filter((s) => s.runtime === entrada.perfil.runtime && s.perfil === entrada.perfil.id && s.viva);
+    for (const sessao of candidatas) {
+        const achados = vinculosDaConta(projetos, sessao.sessionId, contaBruta);
+        falhas.push(...achados.falhas);
+        if (achados.vinculos.length === 0)
+            continue;
+        const pendentes = achados.vinculos.filter((v) => !(0, ledger_1.lerLedger)((0, thread_1.dirThread)(v.raiz, v.thread)).some((e) => e.tipo === 'phase_result' && e.quotaEpisodeId === episodio && e.sessionId === sessao.sessionId));
+        for (const v of achados.vinculos.filter((x) => !pendentes.includes(x))) {
+            sessoes.push({ ...v, sessionId: sessao.sessionId, parada: true, registrada: false, detalhe: 'episódio já reconciliado' });
+        }
+        if (pendentes.length === 0)
+            continue;
+        const paradaUnica = sessao.runtime === 'claude-bg'
+            ? deps.parar(sessao.sessionId, sessao.id, entrada.perfil) : null;
+        for (const v of pendentes) {
+            const parada = paradaUnica ?? deps.parar(sessao.sessionId, sessao.id, entrada.perfil, v);
+            const dir = (0, thread_1.dirThread)(v.raiz, v.thread);
+            if (!parada.ok || !(0, ledger_1.threadPresente)(dir)) {
+                sessoes.push({ ...v, sessionId: sessao.sessionId, parada: parada.ok, registrada: false, detalhe: parada.detalhe });
+                continue;
+            }
+            let registrada = false;
+            (0, session_events_1.comLockDeSessao)(dir, () => {
+                const atuais = (0, ledger_1.lerLedger)(dir);
+                if (atuais.some((e) => e.tipo === 'phase_result' && e.quotaEpisodeId === episodio && e.sessionId === sessao.sessionId))
+                    return;
+                const dados = { fase: v.fase, sessionId: sessao.sessionId, despachoEm: v.despachoEm, runtime: sessao.runtime,
+                    motivo: 'runtime.quota-exhausted', quotaEpisodeId: episodio, conta, resetEm: entrada.falha.resetEm,
+                    esgotadoAte: entrada.esgotadoAte, observadoEm: new Date(agoraMs).toISOString(), origem: 'account.quota-exhausted',
+                    perfil: { id: entrada.perfil.id, runtime: entrada.perfil.runtime },
+                    falhaDeConta: { motivo: entrada.falha.motivo, resetEm: entrada.falha.resetEm,
+                        fonte: entrada.falha.fonte, trecho: entrada.falha.trecho },
+                    evidencia: 'vínculo da sessão, conta do despacho e parada confirmados pelo núcleo' };
+                (0, ledger_1.registrarSeExiste)(dir, v.thread, 'runtime_account_exhausted', dados);
+                (0, ledger_1.registrarSeExiste)(dir, v.thread, ledger_1.TIPOS_DE_EVENTO.gateBloqueado, { ...dados, gate: 'phase.dispatch',
+                    modo: (0, thread_1.lerThread)(v.raiz, v.thread).modo, detalhe: 'a conta do despacho esgotou; retomar no próximo destino capaz',
+                    correcao: `ork retry run ${v.thread}` });
+                (0, ledger_1.registrarSeExiste)(dir, v.thread, 'phase_result', { ...dados, sensorResultId: `quota:${episodio}:${sessao.sessionId}`,
+                    classificacao: 'gate_blocked', ok: false, estado: 'bloqueada', paradaConfirmada: true });
+                registrada = true;
+            });
+            sessoes.push({ ...v, sessionId: sessao.sessionId, parada: true, registrada,
+                detalhe: registrada ? 'sessão parada e condução liberada' : 'episódio já reconciliado' });
+        }
+    }
+    return { conta, episodio, completo: inv.ok && falhas.length === 0 && sessoes.every((s) => s.parada && (s.registrada || s.detalhe.includes('já'))),
+        sessoes, falhas };
+}