@orkastery/cli 0.5.6 → 0.6.1

package/dist/noctum-transporte.js

@@ -0,0 +1,655 @@
+"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.identidadeDoCommit = exports.CHAVE_DO_DESTINO = exports.ID_DA_VAGA = exports.ID_DA_ORDEM = exports.NOME_DE_MAQUINA = exports.TENTATIVAS_DE_GRAVAR = exports.TETO_DE_REGISTROS = exports.TETO_DO_REGISTRO = exports.RECIBOS = exports.TIPOS_DE_REGISTRO = exports.CONTRATO_COORDENACAO = exports.BRANCH_DE_COORDENACAO = void 0;
+exports.identidadeDaMaquina = identidadeDaMaquina;
+exports.assinarDados = assinarDados;
+exports.assinaturaConfere = assinaturaConfere;
+exports.caminhoDoRegistro = caminhoDoRegistro;
+exports.lerRamo = lerRamo;
+exports.euNaVersaoVigente = euNaVersaoVigente;
+exports.gravarNoRamo = gravarNoRamo;
+exports.cabecasNoRemoto = cabecasNoRemoto;
+/**
+ * RM-058, fatia N3 (D1, D5, D6 e D7 da ork-rm058n3): o transporte entre as máquinas de um arco #Noctum.
+ *
+ * O meio é um ramo de estado no remoto do projeto, `ork/noctum-coordenacao`, gravado como as reservas da RM-047: commit em
+ * cima da ponta lida e push sem força (`gravarNaBranch`). Duas máquinas que gravam juntas nunca perdem uma à outra: quem
+ * perdeu a corrida relê e roda a regra de novo sobre o estado novo. Cada registro é assinado pela máquina que o escreveu,
+ * com a chave Ed25519 derivada da chave local do núcleo (D5), e conferido com a chave que o dono autorizou no envelope
+ * `v3` desta máquina. O retrato da rede (RM-053) e o da fábrica (RM-047) são descoberta: nada deles entra aqui.
+ *
+ * A leitura reprova inteira (D6): assinatura, caminho ou máquina que não conferem, arquivo apagado ou alterado (só a
+ * batida é regravada, e nunca para trás no tempo) e história que não desce da última ponta vista por esta máquina recusam
+ * a decisão com `noctum.coordenacao.adulterado`, sem usar a parte que conferiu. O registro de uma versão do envelope que
+ * esta máquina ainda não autorizou é espera, não adulteração (`noctum.coordenacao.versao-nao-autorizada`). A última ponta
+ * vista só avança depois que a leitura inteira conferiu, inclusive a coerência de quem chama. Sem leitura nova do remoto
+ * nada é decidido (D7, `noctum.coordenacao.sem-remoto`): a cópia local do ramo nunca vira fato.
+ *
+ * Cada registro sai assinado sob a versão vigente aqui; o fim do que é desta máquina (recibo de fim, vaga solta, fim da
+ * vez, entrega, revogação) sai também sob a última versão em que ela estava, depois de uma emenda que a tirou do arco. O
+ * commit leva a identidade da máquina, nunca a do git de quem a usa.
+ *
+ * Limites ditos na página: a chave da máquina é legível pelo mesmo usuário do sistema, como a chave local da N1; quem tem
+ * push no remoto pode apagar ou reescrever o ramo, e só a máquina que já viu o registro percebe.
+ */
+const node_child_process_1 = require("node:child_process");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const branch_de_estado_1 = require("./branch-de-estado");
+const estado_thread_1 = require("./estado-thread");
+const fila_pesada_1 = require("./fila-pesada");
+const hitl_local_receipt_1 = require("./hitl-local-receipt");
+const maquina_1 = require("./maquina");
+const noctum_arco_1 = require("./noctum-arco");
+const noctum_envelope_1 = require("./noctum-envelope");
+const roadmap_reservas_1 = require("./roadmap-reservas");
+exports.BRANCH_DE_COORDENACAO = 'ork/noctum-coordenacao';
+exports.CONTRATO_COORDENACAO = 'ork.noctum-coordenacao/v1';
+const CONTRATO_DA_VISTA = 'ork.noctum-coordenacao-vista/v1';
+const PREFIXO = 'noctum';
+const DOMINIO_DA_CHAVE = 'ork.noctum-maquina/v1';
+/** O cabeçalho PKCS#8 de uma chave privada Ed25519; a semente de 32 bytes vem logo depois (o padrão do recibo público). */
+const PKCS8_ED25519 = Buffer.from('302e020100300506032b657004220420', 'hex');
+exports.TIPOS_DE_REGISTRO = ['autoridade', 'cessao', 'ordem', 'cancelamento', 'recibo', 'vaga', 'vaga-solta', 'vez', 'vez-fim',
+    'entrega', 'batida', 'revogacao'];
+exports.RECIBOS = ['aceita', 'recusada', 'concluida', 'encerrada'];
+/** Tetos da leitura: um registro é um JSON curto, e um arco de uma noite não chega perto do número. */
+exports.TETO_DO_REGISTRO = 8 * 1024;
+exports.TETO_DE_REGISTROS = 10000;
+/** Pushes recusados seguidos antes de desistir: o mesmo número das reservas da RM-047. */
+exports.TENTATIVAS_DE_GRAVAR = 5;
+exports.NOME_DE_MAQUINA = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+exports.ID_DA_ORDEM = /^O-([a-z0-9][a-z0-9-]{0,31})-([1-9][0-9]{0,3})$/;
+exports.ID_DA_VAGA = /^V-([A-Za-z0-9][A-Za-z0-9._-]{0,63})-([1-9][0-9]{0,8})$/;
+exports.CHAVE_DO_DESTINO = /^[0-9a-f]{16}$/;
+const adulterado = (detalhe) => new noctum_envelope_1.RecusaDoArco('noctum.coordenacao.adulterado', `${detalhe}; o ramo de coordenação exige inspeção`);
+const semRemoto = (detalhe) => new noctum_envelope_1.RecusaDoArco('noctum.coordenacao.sem-remoto', detalhe);
+const foraDoEnvelope = (detalhe) => new noctum_envelope_1.RecusaDoArco('noctum.coordenacao.fora-do-envelope', detalhe);
+const objeto = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const quatro = (n) => {
+    if (typeof n !== 'number' || !Number.isSafeInteger(n) || n < 1 || n > 9999)
+        throw adulterado(`número de registro inválido (${String(n)})`);
+    return String(n).padStart(4, '0');
+};
+const primeiraLinha = (e) => String(e?.message ?? e).split('\n')[0].slice(0, 300);
+// ---------------------------------------------------------------------------
+// Identidade da máquina (D5).
+// ---------------------------------------------------------------------------
+function chavePrivada(raiz) {
+    const semente = (0, node_crypto_1.createHmac)('sha256', (0, hitl_local_receipt_1.chaveLocal)(raiz, true)).update(DOMINIO_DA_CHAVE).digest();
+    return (0, node_crypto_1.createPrivateKey)({ key: Buffer.concat([PKCS8_ED25519, semente]), format: 'der', type: 'pkcs8' });
+}
+/**
+ * O nome e a chave pública Ed25519 (SPKI DER em base64) desta raiz de estado: é o que o dono põe em `maquinas` no envelope
+ * `v3`. A chave privada nunca sai daqui; ela deriva da chave local do núcleo, que a raiz de estado guarda 0600.
+ */
+function identidadeDaMaquina(raiz, nome) {
+    return { nome: (0, maquina_1.nomeDaMaquina)(nome), chave: (0, node_crypto_1.createPublicKey)(chavePrivada(raiz)).export({ format: 'der', type: 'spki' }).toString('base64') };
+}
+function assinarDados(raiz, dados) {
+    return (0, node_crypto_1.sign)(null, Buffer.from((0, noctum_envelope_1.canonico)(dados), 'utf8'), chavePrivada(raiz)).toString('base64');
+}
+function assinaturaConfere(chave, dados, assinatura) {
+    if (typeof assinatura !== 'string' || !/^[A-Za-z0-9+/]{86}==$/.test(assinatura))
+        return false;
+    try {
+        const publica = (0, node_crypto_1.createPublicKey)({ key: Buffer.from(chave, 'base64'), format: 'der', type: 'spki' });
+        return publica.asymmetricKeyType === 'ed25519' && (0, node_crypto_1.verify)(null, Buffer.from((0, noctum_envelope_1.canonico)(dados), 'utf8'), publica, Buffer.from(assinatura, 'base64'));
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// O caminho de cada registro sai dos dados dele.
+// ---------------------------------------------------------------------------
+/** O caminho do registro no ramo, recalculado dos dados; identificador fora do formato reprova. */
+function caminhoDoRegistro(d) {
+    if (typeof d.arco !== 'string' || !noctum_envelope_1.ID_DO_ARCO.test(d.arco))
+        throw adulterado('registro com arco inválido');
+    const base = `arcos/${d.arco}`;
+    const ordem = () => { if (typeof d.ordem !== 'string' || !exports.ID_DA_ORDEM.test(d.ordem))
+        throw adulterado('registro com ordem inválida'); return d.ordem; };
+    const vaga = () => { if (typeof d.vaga !== 'string' || !exports.ID_DA_VAGA.test(d.vaga))
+        throw adulterado('registro com vaga inválida'); return d.vaga; };
+    const chave = () => { if (typeof d.chave !== 'string' || !exports.CHAVE_DO_DESTINO.test(d.chave))
+        throw adulterado('registro com destino inválido'); return d.chave; };
+    switch (d.tipo) {
+        case 'autoridade': return `${base}/autoridade/${quatro(d.geracao)}.json`;
+        case 'cessao': return `${base}/cessoes/${quatro(d.geracao)}.json`;
+        case 'ordem': return `${base}/ordens/${ordem()}.json`;
+        case 'cancelamento': return `${base}/cancelamentos/${ordem()}.json`;
+        case 'recibo':
+            if (!exports.RECIBOS.includes(d.recibo))
+                throw adulterado('recibo de tipo desconhecido');
+            return `${base}/recibos/${ordem()}/${String(d.recibo)}.json`;
+        case 'vaga': return `${base}/vagas/${vaga()}.json`;
+        case 'vaga-solta': return `${base}/vagas/${vaga()}.solta.json`;
+        case 'vez': return `${base}/integracao/${chave()}/${quatro(d.n)}.json`;
+        case 'vez-fim': return `${base}/integracao/${chave()}/${quatro(d.n)}.fim.json`;
+        case 'entrega':
+            if (typeof d.trabalho !== 'string' || !noctum_envelope_1.ID_DO_TRABALHO.test(d.trabalho))
+                throw adulterado('entrega com trabalho inválido');
+            return `${base}/entregas/${d.trabalho}.json`;
+        case 'batida':
+            if (typeof d.por !== 'string' || !exports.NOME_DE_MAQUINA.test(d.por))
+                throw adulterado('batida com máquina inválida');
+            return `${base}/batidas/${d.por}.json`;
+        case 'revogacao':
+            if (typeof d.por !== 'string' || !exports.NOME_DE_MAQUINA.test(d.por))
+                throw adulterado('revogação com máquina inválida');
+            return `${base}/revogacoes/${d.por}.json`;
+        default: throw adulterado(`registro de tipo desconhecido (${String(d.tipo)})`);
+    }
+}
+/** A batida é o único registro que a máquina regrava; todo o resto é só de acréscimo. */
+const regravavel = (arco, caminho) => new RegExp(`^arcos/${arco}/batidas/[^/]+[.]json$`).test(caminho);
+// ---------------------------------------------------------------------------
+// Git sem limite de saída pequeno: a árvore do arco e os blobs vêm de uma vez.
+// ---------------------------------------------------------------------------
+function gitBruto(raiz, args, entrada) {
+    const r = (0, node_child_process_1.spawnSync)('git', args, { cwd: raiz, input: entrada, maxBuffer: 256 * 1024 * 1024, timeout: 60000 });
+    return { ok: r.status === 0 && !r.error, status: r.status, saida: r.stdout ?? Buffer.alloc(0), erro: (r.stderr ?? Buffer.alloc(0)).toString('utf8') };
+}
+/**
+ * Os arquivos do arco na ponta: modo, objeto, tamanho e caminho. Só blob comum; link, executável ou submódulo reprovam, e o
+ * tamanho confere antes de ler qualquer conteúdo (S5 da rodada 2: um blob enorme nunca entra na memória).
+ */
+function arquivosDaPonta(raiz, ponta, arco) {
+    const r = gitBruto(raiz, ['ls-tree', '-r', '-l', '-z', '--full-tree', ponta, '--', `arcos/${arco}/`]);
+    if (!r.ok)
+        throw semRemoto(`git ls-tree falhou: ${r.erro.trim().split('\n').pop() ?? ''}`);
+    const entradas = r.saida.toString('utf8').split('\0').filter(Boolean);
+    if (entradas.length > exports.TETO_DE_REGISTROS)
+        throw adulterado(`o arco tem ${entradas.length} registros, acima de ${exports.TETO_DE_REGISTROS}`);
+    return entradas.map((e) => {
+        const m = /^(\d{6}) (\w+) ([0-9a-f]{40,64}) +(\d+|-)\t(.+)$/s.exec(e);
+        if (!m || m[1] !== '100644' || m[2] !== 'blob')
+            throw adulterado(`entrada que não é arquivo comum no ramo (${e.slice(0, 80)})`);
+        if (Number(m[4]) > exports.TETO_DO_REGISTRO)
+            throw adulterado(`${m[5]} tem ${m[4]} bytes, acima de ${exports.TETO_DO_REGISTRO}`);
+        return { oid: m[3], caminho: m[5] };
+    });
+}
+/** Os conteúdos dos blobs, numa chamada só de `git cat-file --batch`. */
+function lerBlobs(raiz, oids) {
+    const conteudos = new Map();
+    if (!oids.length)
+        return conteudos;
+    const r = gitBruto(raiz, ['cat-file', '--batch'], oids.join('\n') + '\n');
+    if (!r.ok)
+        throw semRemoto(`git cat-file falhou: ${r.erro.trim().split('\n').pop() ?? ''}`);
+    let i = 0;
+    for (const oid of oids) {
+        const fim = r.saida.indexOf(0x0a, i);
+        const cabeca = r.saida.subarray(i, fim).toString('utf8');
+        const m = /^([0-9a-f]{40,64}) blob (\d+)$/.exec(cabeca);
+        if (!m || m[1] !== oid)
+            throw adulterado(`blob ilegível no ramo (${cabeca.slice(0, 80)})`);
+        const tamanho = Number(m[2]);
+        if (tamanho > exports.TETO_DO_REGISTRO)
+            throw adulterado(`registro de ${tamanho} bytes, acima de ${exports.TETO_DO_REGISTRO}`);
+        conteudos.set(oid, r.saida.subarray(fim + 1, fim + 1 + tamanho));
+        i = fim + 1 + tamanho + 1;
+    }
+    return conteudos;
+}
+// ---------------------------------------------------------------------------
+// A última ponta vista por esta máquina (D6): a história só anda para a frente.
+// ---------------------------------------------------------------------------
+function dirDoArcoLocal(raiz, arco) {
+    if (typeof arco !== 'string' || !noctum_envelope_1.ID_DO_ARCO.test(arco))
+        throw new noctum_envelope_1.RecusaDoArco('noctum.envelope.invalido', 'identificador de arco inválido');
+    const principal = (0, estado_thread_1.raizDoEstado)(raiz);
+    (0, estado_thread_1.exigirEstadoSemLink)(principal, ['.orkastery', 'noctum', 'arcos', arco]);
+    const dir = path.join(principal, '.orkastery', 'noctum', 'arcos', arco);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}
+function lerVista(dir) {
+    const arquivo = path.join(dir, 'coordenacao.json');
+    let bruto;
+    try {
+        const fd = fs.openSync(arquivo, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        try {
+            const st = fs.fstatSync(fd);
+            if (!st.isFile() || st.uid !== process.getuid?.() || (st.mode & 0o077) !== 0)
+                throw adulterado('a última ponta vista não é arquivo privado do núcleo');
+            bruto = fs.readFileSync(fd, 'utf8');
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return {};
+        if (e instanceof noctum_envelope_1.RecusaDoArco)
+            throw e;
+        throw adulterado('a última ponta vista não se lê');
+    }
+    let v;
+    try {
+        v = JSON.parse(bruto);
+    }
+    catch {
+        throw adulterado('a última ponta vista não é JSON');
+    }
+    if (!objeto(v) || v.contrato !== CONTRATO_DA_VISTA || !objeto(v.remotos))
+        throw adulterado('a última ponta vista fora do formato');
+    const vista = {};
+    for (const [remoto, x] of Object.entries(v.remotos)) {
+        if (!objeto(x) || typeof x.ponta !== 'string' || !/^[0-9a-f]{40,64}$/.test(x.ponta) || typeof x.vistoEm !== 'string' ||
+            (x.adulterado !== undefined && (!objeto(x.adulterado) || typeof x.adulterado.em !== 'string' || typeof x.adulterado.detalhe !== 'string'))) {
+            throw adulterado('a última ponta vista fora do formato');
+        }
+        vista[remoto] = { ponta: x.ponta, vistoEm: x.vistoEm,
+            ...(x.adulterado ? { adulterado: { em: x.adulterado.em, detalhe: x.adulterado.detalhe } } : {}) };
+    }
+    return vista;
+}
+function gravarVista(dir, vista) {
+    const temp = path.join(dir, `.coordenacao.${(0, node_crypto_1.randomUUID)()}.tmp`);
+    const fd = fs.openSync(temp, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+    try {
+        fs.writeFileSync(fd, JSON.stringify({ contrato: CONTRATO_DA_VISTA, remotos: vista }) + '\n');
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    fs.renameSync(temp, path.join(dir, 'coordenacao.json'));
+}
+/** A trava curta da última ponta vista: dois processos desta máquina nunca a fazem andar para trás. */
+function comTravaDaVista(dir, executar) {
+    const prazo = Date.now() + 10000;
+    for (;;) {
+        const fd = (0, fila_pesada_1.tentarTravaExclusiva)(path.join(dir, 'coordenacao.lock'));
+        if (fd !== null) {
+            try {
+                return executar();
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+        if (Date.now() >= prazo)
+            throw new noctum_envelope_1.RecusaDoArco('noctum.coordenacao.concorrencia', 'outro processo desta máquina segura a última ponta vista');
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+    }
+}
+const ancestral = (raiz, antigo, novo) => {
+    const r = gitBruto(raiz, ['merge-base', '--is-ancestor', antigo, novo]);
+    if (r.ok)
+        return 'sim';
+    return r.status === 1 ? 'nao' : 'ilegivel';
+};
+/** O `em` de um registro numa ponta, para comparar a batida antiga com a nova. */
+function emDoRegistro(raiz, ponta, caminho) {
+    const r = gitBruto(raiz, ['show', `${ponta}:${caminho}`]);
+    if (!r.ok)
+        return { lido: false, em: NaN };
+    try {
+        return { lido: true, em: Date.parse(String(JSON.parse(r.saida.toString('utf8')).dados.em)) };
+    }
+    catch {
+        return { lido: true, em: NaN };
+    }
+}
+/**
+ * Entre duas pontas da história, só acréscimo, salvo a batida, que nunca volta no tempo (D6 e S3 da revisão). Devolve a
+ * violação que achou, `null` quando só houve acréscimo, ou `ilegivel` quando o diff não se leu.
+ */
+function violacaoDeAcrescimo(raiz, arco, de, para) {
+    const diff = gitBruto(raiz, ['diff', '--name-status', '--no-renames', '-z', de, para, '--', `arcos/${arco}/`]);
+    if (!diff.ok)
+        return 'ilegivel';
+    const partes = diff.saida.toString('utf8').split('\0').filter(Boolean);
+    for (let i = 0; i + 1 < partes.length; i += 2) {
+        const [status, caminho] = [partes[i], partes[i + 1]];
+        if (status === 'A')
+            continue;
+        if (status === 'M' && regravavel(arco, caminho)) {
+            const nova = emDoRegistro(raiz, para, caminho), antiga = emDoRegistro(raiz, de, caminho);
+            if (!nova.lido || !antiga.lido)
+                return 'ilegivel';
+            if (!(nova.em >= antiga.em))
+                return `a batida ${caminho} voltou no tempo depois de vista`;
+            continue;
+        }
+        return `o registro ${caminho} foi ${status === 'D' ? 'apagado' : 'alterado'} depois de visto`;
+    }
+    return null;
+}
+/**
+ * Confere a ponta lida contra a última vista, com a trava da vista nas mãos de quem chama: `atras` quando outro processo
+ * desta máquina já viu uma ponta mais nova e, entre as duas, só houve acréscimo (a leitura ficou velha, não adulterada).
+ * Nos dois sentidos, o apagamento, a alteração e a história reescrita reprovam e marcam a vista (A-R2A-1 da rodada 2): o
+ * que um processo desta máquina viu, nenhum outro faz esquecer.
+ */
+function relacaoComAVista(raiz, dir, remoto, arco, ponta, quando) {
+    const vista = lerVista(dir);
+    const atual = vista[remoto];
+    if (atual?.adulterado) {
+        throw adulterado(`esta máquina já viu o ramo adulterado em ${atual.adulterado.em} (${atual.adulterado.detalhe}); a última ponta vista ` +
+            'fica marcada até a inspeção');
+    }
+    const antiga = atual?.ponta ?? null;
+    if (antiga === null)
+        return 'ok';
+    const reprovar = (detalhe) => {
+        gravarVista(dir, { ...vista, [remoto]: { ...atual, adulterado: { em: quando, detalhe: detalhe.slice(0, 300) } } });
+        throw adulterado(detalhe);
+    };
+    const conferir = (de, para) => {
+        const v = violacaoDeAcrescimo(raiz, arco, de, para);
+        if (v === 'ilegivel')
+            throw adulterado('o diff entre a última ponta vista e a nova não se lê');
+        if (v)
+            reprovar(v);
+    };
+    if (ponta === null)
+        return reprovar(`o ramo ${exports.BRANCH_DE_COORDENACAO} sumiu do remoto ${remoto} depois de visto`);
+    if (ponta === antiga)
+        return 'ok';
+    const adiante = ancestral(raiz, antiga, ponta);
+    if (adiante === 'ilegivel')
+        throw adulterado('a relação entre a última ponta vista e a nova não se lê');
+    if (adiante === 'sim') {
+        conferir(antiga, ponta);
+        return 'ok';
+    }
+    const atras = ancestral(raiz, ponta, antiga);
+    if (atras === 'ilegivel')
+        throw adulterado('a relação entre a nova ponta e a última vista não se lê');
+    if (atras === 'sim') {
+        conferir(ponta, antiga);
+        return 'atras';
+    }
+    return reprovar(`a história do ramo foi reescrita: a ponta ${ponta.slice(0, 12)} não desce da última vista ${antiga.slice(0, 12)}`);
+}
+/** Grava a ponta como a última vista; só com a trava da vista e depois de `relacaoComAVista` dizer `ok`. */
+function gravarPonta(dir, remoto, ponta, quando) {
+    if (!ponta)
+        return;
+    const vista = lerVista(dir);
+    if (vista[remoto]?.ponta === ponta)
+        return;
+    gravarVista(dir, { ...vista, [remoto]: { ponta, vistoEm: quando } });
+}
+/**
+ * Avança a última ponta vista para o commit que esta máquina acabou de gravar, conferido nos dois sentidos contra a vista
+ * de agora (outro processo pode ter visto uma ponta mais nova, e o registro gravado aqui não pode ter sumido dela).
+ */
+function avancarVista(raiz, dir, remoto, arco, ponta, quando) {
+    comTravaDaVista(dir, () => {
+        if (relacaoComAVista(raiz, dir, remoto, arco, ponta, quando) === 'ok')
+            gravarPonta(dir, remoto, ponta, quando);
+    });
+}
+// ---------------------------------------------------------------------------
+// Leitura e gravação.
+// ---------------------------------------------------------------------------
+function remotoDe(carregado, opcoes) {
+    try {
+        return (0, branch_de_estado_1.exigirRemoto)(opcoes.remoto ?? carregado.manifesto.fabrica.remoto, PREFIXO);
+    }
+    catch (e) {
+        throw semRemoto(primeiraLinha(e));
+    }
+}
+const redeDe = (raiz, opcoes) => opcoes.rede ?? (0, roadmap_reservas_1.redeDoFechamento)(raiz);
+/** As versões autorizadas aqui que são de várias máquinas, pelo hash: só elas assinam no ramo. */
+function chavesPorVersao(versoes) {
+    const porHash = new Map();
+    for (const v of versoes) {
+        if ((0, noctum_envelope_1.envelopeMultimaquina)(v.conteudo))
+            porHash.set(v.envelopeSha256, new Map(v.conteudo.maquinas.map(m => [m.nome, m.chave])));
+    }
+    return porHash;
+}
+function lerUmaVez(carregado, arco, opcoes, conferir) {
+    const { raiz } = carregado;
+    const quando = opcoes.quando ?? new Date().toISOString();
+    const remoto = remotoDe(carregado, opcoes);
+    const versoes = (0, noctum_arco_1.versoesAutorizadas)(raiz, arco);
+    if (!versoes.length)
+        throw foraDoEnvelope(`o arco ${arco} não tem envelope autorizado nesta máquina`);
+    const dir = dirDoArcoLocal(raiz, arco);
+    const chaves = chavesPorVersao(versoes);
+    const rede = redeDe(raiz, opcoes);
+    let lida;
+    try {
+        lida = (0, branch_de_estado_1.buscarBranch)(raiz, remoto, exports.BRANCH_DE_COORDENACAO, PREFIXO, rede.timeoutMs, rede.env);
+    }
+    catch (e) {
+        throw semRemoto(primeiraLinha(e));
+    }
+    if (!lida.atualizado)
+        throw semRemoto(`não consegui ler ${exports.BRANCH_DE_COORDENACAO} em ${remoto}; sem leitura nova, nada é decidido`);
+    const registros = [];
+    if (lida.ponta) {
+        const arquivos = arquivosDaPonta(raiz, lida.ponta, arco);
+        const blobs = lerBlobs(raiz, arquivos.map(a => a.oid));
+        for (const { oid, caminho } of arquivos) {
+            let bruto;
+            try {
+                bruto = JSON.parse(blobs.get(oid).toString('utf8'));
+            }
+            catch {
+                throw adulterado(`${caminho} não é JSON`);
+            }
+            if (!objeto(bruto) || Object.keys(bruto).sort().join(',') !== 'assinatura,dados' || !objeto(bruto.dados)) {
+                throw adulterado(`${caminho} fora do formato`);
+            }
+            const d = bruto.dados;
+            if (d.contrato !== exports.CONTRATO_COORDENACAO || d.arco !== arco || !exports.TIPOS_DE_REGISTRO.includes(d.tipo) ||
+                typeof d.em !== 'string' || !Number.isFinite(Date.parse(d.em))) {
+                throw adulterado(`${caminho} fora do contrato`);
+            }
+            const daVersao = typeof d.envelopeSha256 === 'string' ? chaves.get(d.envelopeSha256) : undefined;
+            // A3 da revisão: a emenda que a outra máquina já autorizou e esta ainda não é espera, não adulteração.
+            if (!daVersao) {
+                throw new noctum_envelope_1.RecusaDoArco('noctum.coordenacao.versao-nao-autorizada', `${caminho} é de uma versão do envelope que esta máquina ` +
+                    'ainda não autorizou: se o dono autorizou uma emenda em outra máquina, autorize-a aqui, na mesma ordem das outras máquinas; se não houve emenda, o ramo exige ' +
+                    'inspeção. Até lá, esta máquina não decide nem grava no ramo');
+            }
+            const chave = typeof d.por === 'string' ? daVersao.get(d.por) : undefined;
+            if (!chave)
+                throw adulterado(`${caminho} assinado por uma máquina fora do envelope (${String(d.por).slice(0, 64)})`);
+            if (!assinaturaConfere(chave, d, bruto.assinatura))
+                throw adulterado(`${caminho} com assinatura que não confere`);
+            if (caminhoDoRegistro(d) !== caminho)
+                throw adulterado(`${caminho} não é o caminho dos dados dele`);
+            registros.push({ caminho, dados: d });
+        }
+    }
+    const leitura = { arco, remoto, ponta: lida.ponta, registros, versoes, lidoEm: quando };
+    // A2 da revisão e A-R2A-1 da rodada 2: a história, a coerência de quem chama e o avanço da vista numa seção crítica só.
+    // Nenhum outro processo desta máquina avança a vista entre conferir e gravar, e a vista só anda depois da coerência.
+    return comTravaDaVista(dir, () => {
+        if (relacaoComAVista(raiz, dir, remoto, arco, lida.ponta, quando) === 'atras')
+            return 'atras';
+        conferir?.(leitura);
+        gravarPonta(dir, remoto, lida.ponta, quando);
+        return leitura;
+    });
+}
+/**
+ * A leitura conferida do ramo de coordenação do arco, nova do remoto. Lança a recusa tipada; nunca devolve leitura
+ * parcial. Outro processo desta máquina que já viu uma ponta mais nova faz esta ler de novo; a ponta que continua atrás da
+ * última vista depois de três leituras é o ramo que voltou atrás (push forçado para um commit antigo), e reprova.
+ */
+function lerRamo(carregado, arco, opcoes = {}, conferir) {
+    for (let tentativa = 1; tentativa <= 3; tentativa++) {
+        const lida = lerUmaVez(carregado, arco, opcoes, conferir);
+        if (lida !== 'atras')
+            return lida;
+    }
+    throw adulterado('a história do ramo foi reescrita: a ponta do remoto voltou para trás da última vista por esta máquina');
+}
+/** A versão vigente aqui (a última autorizada) e esta máquina nela, com o mesmo nome e a mesma chave; senão, a recusa. */
+function euNaVersaoVigente(raiz, leitura, opcoes) {
+    const vigente = leitura.versoes.at(-1);
+    if (!(0, noctum_envelope_1.envelopeMultimaquina)(vigente.conteudo)) {
+        throw foraDoEnvelope(`o envelope vigente do arco ${leitura.arco} é ${vigente.conteudo.contrato}, sem máquinas: só a v3 coordena`);
+    }
+    const eu = identidadeDaMaquina(raiz, opcoes.maquina);
+    const listada = vigente.conteudo.maquinas.find(m => m.nome === eu.nome);
+    if (!listada)
+        throw foraDoEnvelope(`a máquina ${eu.nome} não está no envelope vigente do arco ${leitura.arco}`);
+    if (listada.chave !== eu.chave)
+        throw foraDoEnvelope(`a chave desta raiz não é a que o envelope dá à máquina ${eu.nome}`);
+    return { eu, vigente };
+}
+/** Os registros com que uma máquina fecha o que é dela; só eles saem sob uma versão anterior do envelope (A4 da revisão). */
+const ehFechamento = (c) => c.tipo === 'vaga-solta' || c.tipo === 'vez-fim' || c.tipo === 'entrega' ||
+    c.tipo === 'revogacao' || (c.tipo === 'recibo' && (c.recibo === 'concluida' || c.recibo === 'encerrada'));
+/**
+ * A versão sob a qual esta máquina assina: a vigente; ou, quando uma emenda a tirou do arco, a última versão autorizada em
+ * que ela está com a mesma chave, e só para fechar o que é dela (fim de ordem, vaga, vez e entrega). O leitor confere cada
+ * registro com as chaves da versão que ele diz.
+ */
+function versaoParaAssinar(raiz, leitura, opcoes, novos) {
+    try {
+        return euNaVersaoVigente(raiz, leitura, opcoes);
+    }
+    catch (e) {
+        if (!(e instanceof noctum_envelope_1.RecusaDoArco) || e.motivo !== 'noctum.coordenacao.fora-do-envelope' || !novos.every(ehFechamento))
+            throw e;
+        const eu = identidadeDaMaquina(raiz, opcoes.maquina);
+        const antiga = [...leitura.versoes].reverse().find(v => (0, noctum_envelope_1.envelopeMultimaquina)(v.conteudo) &&
+            v.conteudo.maquinas.some(m => m.nome === eu.nome && m.chave === eu.chave));
+        if (!antiga)
+            throw e;
+        return { eu, vigente: antiga };
+    }
+}
+/** A identidade dos commits do ramo de coordenação: a máquina, num domínio reservado que não entrega e-mail. */
+const identidadeDoCommit = (maquina) => ({ nome: `ork-noctum ${maquina}`, email: 'ork-noctum@noctum.invalid' });
+exports.identidadeDoCommit = identidadeDoCommit;
+/**
+ * Grava os registros que a regra pede, assinados por esta máquina sob a versão vigente do envelope, numa versão nova do
+ * ramo em cima da ponta lida. Push recusado: relê e roda a regra de novo, até `TENTATIVAS_DE_GRAVAR`. A regra pode lançar a
+ * recusa tipada e deve ser idempotente, porque um push de resultado incerto é repetido sobre a leitura seguinte.
+ */
+function gravarNoRamo(carregado, arco, opcoes, regra, conferir) {
+    const { raiz } = carregado;
+    const quando = opcoes.quando ?? new Date().toISOString();
+    // S-R3A-1 da rodada 3: o instante vai ao `em` de cada registro, e o leitor o exige como data.
+    if (typeof quando !== 'string' || !Number.isFinite(Date.parse(quando))) {
+        throw new noctum_envelope_1.RecusaDoArco('noctum.envelope.invalido', 'o instante da gravação não é uma data; nada foi ao ramo');
+    }
+    for (let tentativa = 1; tentativa <= exports.TENTATIVAS_DE_GRAVAR; tentativa++) {
+        const leitura = lerRamo(carregado, arco, { ...opcoes, quando }, conferir);
+        const { novos, resultado } = regra(leitura);
+        if (!novos.length)
+            return { resultado, commit: null, gravados: [], leitura };
+        const { eu, vigente } = versaoParaAssinar(raiz, leitura, opcoes, novos);
+        const existentes = new Set(leitura.registros.map(r => r.caminho));
+        const mudancas = [];
+        const gravados = [];
+        for (const campos of novos) {
+            // B1 da rodada 2: o que se assina é o que o leitor vai ler, sem campo `undefined` nem objeto que o JSON transforma.
+            const dados = JSON.parse(JSON.stringify({ ...campos, contrato: exports.CONTRATO_COORDENACAO, arco, envelopeSha256: vigente.envelopeSha256,
+                por: eu.nome, em: quando }));
+            const caminho = caminhoDoRegistro(dados);
+            // S3 da revisão: a batida desta máquina nunca volta no tempo, nem quando o relógio daqui volta.
+            const anterior = dados.tipo === 'batida' ? leitura.registros.find(r => r.caminho === caminho)?.dados.em : undefined;
+            if (anterior && Date.parse(anterior) > Date.parse(quando))
+                dados.em = anterior;
+            if ((existentes.has(caminho) && !regravavel(arco, caminho)) || mudancas.some(m => m.caminho === caminho)) {
+                throw new noctum_envelope_1.RecusaDoArco('noctum.coordenacao.concorrencia', `o registro ${caminho} já existe; a regra não é idempotente nele`);
+            }
+            const conteudo = JSON.stringify({ dados, assinatura: assinarDados(raiz, dados) }) + '\n';
+            if (Buffer.byteLength(conteudo) > exports.TETO_DO_REGISTRO)
+                throw new noctum_envelope_1.RecusaDoArco('noctum.envelope.invalido', `o registro ${caminho} passa de ${exports.TETO_DO_REGISTRO} bytes`);
+            mudancas.push({ caminho, conteudo });
+            gravados.push(dados);
+        }
+        // S-R3A-1 da rodada 3: o teto de registros por arco, que o leitor confere, também vale para quem grava.
+        if (leitura.registros.length + mudancas.filter(m => !existentes.has(m.caminho)).length > exports.TETO_DE_REGISTROS) {
+            throw new noctum_envelope_1.RecusaDoArco('noctum.envelope.invalido', `o arco passaria de ${exports.TETO_DE_REGISTROS} registros; nada foi ao ramo`);
+        }
+        // B1 da rodada 2: quem grava confere com a régua de quem lê, em memória e antes do push. O registro que as máquinas
+        // reprovariam (e que travaria o arco em todas) fica aqui, como pedido inválido, e nada vai ao ramo.
+        if (conferir) {
+            const trocados = new Set(mudancas.map(m => m.caminho));
+            const projetada = { ...leitura, registros: [...leitura.registros.filter(r => !trocados.has(r.caminho)),
+                    ...gravados.map((dados, i) => ({ caminho: mudancas[i].caminho, dados }))] };
+            try {
+                conferir(projetada);
+            }
+            catch (e) {
+                if (!(e instanceof noctum_envelope_1.RecusaDoArco) || e.motivo !== 'noctum.coordenacao.adulterado')
+                    throw e;
+                const porque = e.message.slice(`${e.motivo}: `.length).replace(/; o ramo de coordenação exige inspeção$/, '');
+                throw new noctum_envelope_1.RecusaDoArco('noctum.envelope.invalido', `as máquinas reprovariam o que esta gravação pede (${porque}); nada foi ao ramo`);
+            }
+        }
+        const tipos = [...new Set(gravados.map(g => g.tipo))].join(', ');
+        let commit;
+        try {
+            // S6 da revisão: o commit leva o nome da máquina, nunca o nome e o e-mail do git de quem a usa.
+            commit = (0, branch_de_estado_1.gravarNaBranch)(raiz, leitura.remoto, exports.BRANCH_DE_COORDENACAO, leitura.ponta, mudancas, `noctum: ${arco}, ${tipos} por ${eu.nome}`, PREFIXO, redeDe(raiz, opcoes), (0, exports.identidadeDoCommit)(eu.nome));
+        }
+        catch (e) {
+            throw semRemoto(primeiraLinha(e));
+        }
+        if (commit) {
+            avancarVista(raiz, dirDoArcoLocal(raiz, arco), leitura.remoto, arco, commit, quando);
+            return { resultado, commit, gravados, leitura };
+        }
+    }
+    throw new noctum_envelope_1.RecusaDoArco('noctum.coordenacao.concorrencia', `${exports.TENTATIVAS_DE_GRAVAR} pushes recusados seguidos no ramo de coordenação; tente de novo em instantes`);
+}
+/** As cabeças das branches pedidas no remoto, numa chamada de `git ls-remote`, só leitura. */
+function cabecasNoRemoto(carregado, branches, opcoes = {}) {
+    const { raiz } = carregado;
+    const remoto = remotoDe(carregado, opcoes);
+    const rede = redeDe(raiz, opcoes);
+    const r = (0, node_child_process_1.spawnSync)('git', ['ls-remote', '--', remoto, ...branches.map(b => `refs/heads/${b}`)], { cwd: raiz, encoding: 'utf8', timeout: rede.timeoutMs ?? 15000, env: { ...process.env, ...rede.env } });
+    if (r.status !== 0 || r.error)
+        throw semRemoto(`git ls-remote falhou em ${remoto}: ${(r.stderr ?? '').trim().split('\n').pop() ?? ''}`);
+    const cabecas = new Map(branches.map(b => [b, null]));
+    for (const linha of String(r.stdout).split('\n')) {
+        const m = /^([0-9a-f]{40,64})\trefs\/heads\/(.+)$/.exec(linha.trim());
+        if (m && cabecas.has(m[2]))
+            cabecas.set(m[2], m[1]);
+    }
+    return cabecas;
+}