dd-harness 0.38.2 → 0.40.0

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { diagnostico } from "./diagnostico.js";
-import { aplicaAtualizacao, diagnosticaAtualizacao, versaoInstalada, versaoPublicada } from "./atualizar.js";
+import { aplicaAtualizacao, diagnosticaAtualizacao, reescrevePonteiros, versaoInstalada, versaoPublicada } from "./atualizar.js";
 import { instalaHosts, selecionaHosts } from "./hosts.js";
 import { achaRaiz } from "./config.js";
 import { abreSessao, guardaSessao, saidaDaGuarda, saidaDoBoot } from "./sessao.js";
@@ -27,7 +27,7 @@ import { pergunta, escolha, fechaPerguntas } from "./pergunta.js";
 import { buscaPolitica } from "./politica.js";
 import { avisoDeOrdem, blocoDeSessao, criaFase, editaFase, formataChangelog, formataRoadmap, leFases, } from "./roadmap.js";
 import { decideDoHook, guardaCache } from "./cinto.js";
-import { escrevePonteirosDeSkills, leSkill, leSkills, semeiaSkills } from "./skill.js";
+import { criaSkill, editaSkill, escrevePonteirosDeSkills, leSkill, leSkills, semeiaSkills } from "./skill.js";
 import { SKILLS_INICIAIS } from "./skills-iniciais.js";
 import { busca } from "./buscar.js";
 import { apaga, arquiva, edita, le, promove } from "./curar.js";
@@ -80,7 +80,7 @@ const AJUDA = `dd-harness — a política e o Brain do projeto, no serviço
                                      projeto do espaço, inclusive os futuros
   dd-harness despromover <pasta>/<slug>
                                      traz de volta ao alcance dos vínculos
-  dd-harness apagar <pasta>/<slug> [--confirmar <espaço>]
+  dd-harness apagar <pasta>/<slug> [--confirmar "<frase devolvida>"]
                                      apaga de vez, em cascata — sem desfazer.
                                      Para tirar de circulação guardando o
                                      conteúdo, use "arquivar"
@@ -101,6 +101,11 @@ const AJUDA = `dd-harness — a política e o Brain do projeto, no serviço
   dd-harness skills                 as skills deste projeto e quando cada uma serve
   dd-harness skill <nome>           o procedimento de uma delas (o mesmo que o
                                      agente recebe ao invocá-la)
+  dd-harness skill criar <nome> --descricao "<quando invocar>" [--conteudo <arquivo.md>]
+                     [--so-por-comando true|false]
+  dd-harness skill editar <nome> [--descricao "<d>"] [--conteudo <arquivo.md>]
+                     [--so-por-comando true|false]
+                                     grava no serviço e reescreve o ponteiro em disco
   dd-harness roadmap                as fases abertas: a atual inteira, as próximas
                                      por título (opcional — projeto sem fase não tem)
   dd-harness changelog [--versao <v>]
@@ -140,11 +145,9 @@ function argumento(argv, nome) {
 const API_PADRAO = "https://dd-harness.vercel.app";
 // --- roadmap e changelog ---
 /**
- * `skills` e `skill <slug>` — so LEITURA.
- *
- * Criar e editar ficam na interface de proposito: escrever procedimento e trabalho de
- * texto longo, e um editor de verdade e melhor que um flag de linha de comando. O que o
- * terminal precisa e ver o que existe e conferir um procedimento sem trocar de janela.
+ * `skills` e `skill <slug>` — leitura. Criar e editar sao `skill criar|editar`, com o
+ * procedimento vindo de um .md (`--conteudo`), como em `fase` e `gravar`: sem isso a skill
+ * `escrever-skill` redigia o texto e nao tinha como grava-lo fora da interface.
  */
 async function comandoSkills() {
     const skills = await leSkills(process.cwd());
@@ -160,10 +163,44 @@ async function comandoSkills() {
     }
     console.log(`${skills.length} skill(s). \`dd-harness skill <nome>\` mostra o procedimento.`);
 }
+/** `--so-por-comando true|false`: flag solta seria so "ligar", e desligar tambem e edicao. */
+function soPorComandoDoArgv(argv) {
+    const v = argumento(argv, "so-por-comando");
+    if (v === undefined)
+        return undefined;
+    if (v !== "true" && v !== "false")
+        throw new Error("--so-por-comando: use true ou false.");
+    return v === "true";
+}
+/**
+ * `skill criar` e `skill editar`. O ponteiro em disco e reescrito em seguida: descricao e
+ * "so por comando" moram no frontmatter dele, e o host so le o disco.
+ */
+async function comandoSkillEscrita(acao, argv) {
+    const [slug, ...opcoes] = argv;
+    if (!slug || slug.startsWith("--"))
+        throw new Error(`skill ${acao} exige o nome da skill.`);
+    const campos = {
+        descricao: argumento(opcoes, "descricao"),
+        conteudo: await conteudoDoArgv(opcoes),
+        so_por_comando: soPorComandoDoArgv(opcoes),
+    };
+    if (acao === "criar") {
+        if (!campos.descricao)
+            throw new Error('skill criar exige --descricao "<quando invocar>".');
+        await criaSkill(process.cwd(), { ...campos, slug, descricao: campos.descricao, conteudo: campos.conteudo ?? "" });
+    }
+    else {
+        await editaSkill(process.cwd(), slug, campos);
+    }
+    console.log(`Skill ${slug} ${acao === "criar" ? "criada" : "atualizada"}; ${await reescrevePonteiros(process.cwd())}.`);
+}
 async function comandoSkill(argv) {
     const slug = argv[0];
+    if (slug === "criar" || slug === "editar")
+        return comandoSkillEscrita(slug, argv.slice(1));
     if (!slug || slug.startsWith("-")) {
-        throw new Error("uso: dd-harness skill <nome>");
+        throw new Error("uso: dd-harness skill <nome>  |  dd-harness skill criar|editar <nome> [...]");
     }
     const s = await leSkill(process.cwd(), slug);
     console.log(`# ${s.slug}
@@ -691,21 +728,21 @@ async function comandoPromover(argv, global) {
 /**
  * `apagar` — o unico caminho que destroi.
  *
- * Duas etapas, e a segunda pede o nome do espaco digitado. Nao e cerimonia: a cascata leva
+ * Duas etapas, e a segunda pede a frase vinculada à versão atual. Nao e cerimonia: a cascata leva
  * ancoras e toda a deriva medida delas, e nao ha desfazer. Arquivar continua sendo o
  * caminho normal — isto e para o que nunca deveria ter existido.
  */
 async function comandoApagar(argv) {
     const endereco = argv[0];
     if (!endereco || endereco.startsWith("-") || !endereco.includes("/")) {
-        throw new Error("uso: dd-harness apagar <pasta>/<slug> [--confirmar <espaço>]");
+        throw new Error('uso: dd-harness apagar <pasta>/<slug> [--confirmar "<frase devolvida>"]');
     }
     const r = await apaga(process.cwd(), endereco, argumento(argv, "confirmar"));
     if (!r.apagou) {
         console.log(r.detalhe);
         if (r.confirmacaoEsperada) {
             console.log(`
-  dd-harness apagar ${endereco} --confirmar ${r.confirmacaoEsperada}`);
+  dd-harness apagar ${endereco} --confirmar "${r.confirmacaoEsperada}"`);
         }
         // Sem exit diferente de zero: recusar por falta de confirmacao nao e falha, e o
         // caminho normal da primeira chamada.

package/dist/init.js

@@ -8,13 +8,13 @@ import { CAMINHO_CONFIG } from "./config.js";
  * onde falha silenciosa nasce — entrada errada nao da erro, a ferramenta so nao aparece.
  * Quem cola sabe o que colou.
  */
-export const SUGESTAO_MCP = `{
-  "mcpServers": {
-    "dd-harness": {
-      "command": "npx",
-      "args": ["-y", "dd-harness-mcp"]
-    }
-  }
+export const SUGESTAO_MCP = `{
+  "mcpServers": {
+    "dd-harness": {
+      "command": "npx",
+      "args": ["-y", "dd-harness-mcp"]
+    }
+  }
 }`;
 /**
  * Os dois hooks do dd-harness, pelas duas razoes que nenhuma instrucao em markdown
@@ -33,31 +33,31 @@ export const SUGESTAO_MCP = `{
  *
  * Sugerido e nao escrito, pelo mesmo motivo do `.mcp.json`.
  */
-export const SUGESTAO_HOOK = `{
-  "hooks": {
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "dd-harness politica --hook",
-            "statusMessage": "Carregando a política do dd-harness..."
-          }
-        ]
-      }
-    ],
-    "PreToolUse": [
-      {
-        "matcher": "Edit|Write|MultiEdit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "dd-harness cinto"
-          }
-        ]
-      }
-    ]
-  }
+export const SUGESTAO_HOOK = `{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "dd-harness politica --hook",
+            "statusMessage": "Carregando a política do dd-harness..."
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "dd-harness cinto"
+          }
+        ]
+      }
+    ]
+  }
 }`;
 /**
  * O que escrever num `AGENTS.md`, para agente que NAO e o Claude Code.
@@ -71,19 +71,19 @@ export const SUGESTAO_HOOK = `{
  * simplesmente nunca perguntar pela politica. Dai esta linha, que e curta de proposito —
  * ela manda buscar a regra, nao repete a regra.
  */
-export const SUGESTAO_AGENTS = `# AGENTS.md
-
-Este projeto tem um protocolo de trabalho que **não está neste arquivo**.
-
-**ANTES de qualquer outra coisa**, chame a ferramenta MCP \`ler_artefato\` com
-\`tipo: "politica"\` e siga o que ela devolver. É a primeira ação da sessão, antes
-de ler código, responder ou planejar.
-
-- Se a ferramenta não existir, o servidor MCP do dd-harness não está declarado:
-  avise o usuário e **não modifique nada** até ele resolver.
-- Se ela devolver vazio, este projeto nunca foi briefado — diga isso ao usuário.
-
-O Claude Code carrega a política sozinho, por hook. Nas outras ferramentas, a
+export const SUGESTAO_AGENTS = `# AGENTS.md
+
+Este projeto tem um protocolo de trabalho que **não está neste arquivo**.
+
+**ANTES de qualquer outra coisa**, chame a ferramenta MCP \`ler_artefato\` com
+\`tipo: "politica"\` e siga o que ela devolver. É a primeira ação da sessão, antes
+de ler código, responder ou planejar.
+
+- Se a ferramenta não existir, o servidor MCP do dd-harness não está declarado:
+  avise o usuário e **não modifique nada** até ele resolver.
+- Se ela devolver vazio, este projeto nunca foi briefado — diga isso ao usuário.
+
+O Claude Code carrega a política sozinho, por hook. Nas outras ferramentas, a
 chamada acima é o que substitui esse hook.`;
 async function declaraMcp(raiz) {
     try {

package/dist/materializa.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Do payload do contrato para arquivos em disco.
+ *
+ * Funcao pura de proposito: recebe o Brain e devolve caminho -> conteudo, sem rede e sem
+ * `fs`. E a parte que precisa de teste — o formato tem que casar com o que o
+ * `validate_brain.cjs` do molde espera (frontmatter `name` igual ao arquivo, `pasta`
+ * igual a pasta que o contem, e uma linha de indice por memoria).
+ */
+export type Ancora = {
+    tipo: string;
+    valor: string;
+    sha: string | null;
+};
+export type Memoria = {
+    pasta: string;
+    slug: string;
+    titulo: string;
+    resumo: string;
+    corpo: string;
+    status: "ativa" | "historico";
+    dano: string;
+    invisibilidade: string;
+    externalidade: string;
+    ancoras: Ancora[];
+    revisar_ate: string | null;
+    /** Observacoes de deriva esperando julgamento. Ausente em payload antigo. */
+    deriva_aberta?: number;
+};
+export type Brain = {
+    tenant: {
+        slug: string;
+        nome: string;
+    };
+    projeto: {
+        slug: string;
+        nome: string;
+    };
+    /** `CLAUDE.md`. Nulo ou vazio: ainda nao existe, e nao vira arquivo. */
+    politica?: string | null;
+    /** `BRIEFING.md`. Mesma regra. */
+    briefing?: string | null;
+    pastas: {
+        slug: string;
+        definicao: string;
+    }[];
+    memorias: Memoria[];
+    /**
+     * Memorias que excederam as tentativas de indexacao e nao serao mais tentadas. Ficam
+     * sem embedding — somem da busca semantica — e so este numero denuncia.
+     */
+    travadas_na_fila?: number;
+};
+export declare function arquivoDaMemoria(m: Memoria): string;
+export declare function arquivoDoIndice(brain: Brain): string;
+/** Tudo o que o servico gera vive aqui — e nada fora daqui e escrito pelo `sync`. */
+export declare const PASTA = "dd-harness";
+/** O que a raiz precisa conter para a politica chegar a sessao. */
+export declare const LINHA_DE_IMPORT = "@dd-harness/politica.md";
+/**
+ * Caminho relativo (POSIX) -> conteúdo. As chaves são o que o manifesto guarda.
+ *
+ * Tudo dentro de `dd-harness/`, inclusive a política. Na raiz fica só o `CLAUDE.md`, que
+ * é **seu**: o `sync` não o escreve, apenas confere que ele importa a política. É o que
+ * deixa conviverem a parte gerenciada e o que aquele repositório tem de próprio — e o
+ * que faz adotar um projeto existente ser uma linha, não um ritual.
+ *
+ * Artefato vazio ou ausente não entra no mapa; como o manifesto remove o que saiu do
+ * conjunto, esvaziar no serviço apaga o arquivo no próximo `sync`.
+ */
+export declare function materializa(brain: Brain, pasta?: string): Map<string, string>;

package/dist/materializa.js

@@ -28,9 +28,14 @@ function secaoDeFiltros(m) {
     ].join("\n");
 }
 export function arquivoDaMemoria(m) {
+    // `titulo` vai no frontmatter porque `gravar` e `editar` o exigem la: sem ele o arquivo
+    // materializado nao volta pelo `editar`, e o ciclo "sincroniza, corrige, manda de volta"
+    // — que e como o agente cura memoria — para com "frontmatter sem `titulo`". O titulo
+    // tambem aparece no indice, mas indice nao e o que se edita.
     const frontmatter = [
         "---",
         `name: ${m.slug}`,
+        `titulo: ${m.titulo.replace(/\n/g, " ")}`,
         `description: ${m.resumo.replace(/\n/g, " ")}`,
         `pasta: ${m.pasta}`,
         ...(m.revisar_ate ? [`revisar-ate: ${m.revisar_ate.slice(0, 10)}`] : []),

package/dist/moldes-historicos.js

@@ -10,81 +10,81 @@
  */
 export const MOLDES_HISTORICOS = [
     // ca1e529
-    `## Protocolo do dd-harness
-
-Este projeto tem um protocolo de trabalho que **não está neste arquivo**.
-
-**ANTES de qualquer outra coisa**, chame a ferramenta MCP \`ler_artefato\` com
-\`tipo: "politica"\` e siga o que ela devolver. É a primeira ação da sessão, antes
-de ler código, responder ou planejar.
-
-- Se a ferramenta não existir, o servidor MCP do dd-harness não está declarado:
-  avise o usuário e **não modifique nada** até ele resolver.
-- Se ela devolver vazio, este projeto nunca foi briefado — diga isso ao usuário.
-
-Leia também o briefing com a mesma ferramenta (tipo briefing). Os dois são obrigatórios.
-
-Depois, \`ler_roadmap\`: se houver uma fase **Agora**, é dela que saem os passos
-desta sessão. Lista vazia significa que este projeto não usa roadmap, e isso é
-válido — não crie fase sem o usuário pedir.
-
-E \`listar_skills\`: são os procedimentos deste projeto. **Invoque a que couber
-ANTES de fazer o trabalho, não depois** — skill lida no fim vira revisão do que
-já saiu errado, e é tarde.
-
-Vale mesmo quando o pedido parece pequeno: "é só um ajuste" é exatamente a
-frase que antecede pular o procedimento. A política diz quais são obrigatórias
+    `## Protocolo do dd-harness
+
+Este projeto tem um protocolo de trabalho que **não está neste arquivo**.
+
+**ANTES de qualquer outra coisa**, chame a ferramenta MCP \`ler_artefato\` com
+\`tipo: "politica"\` e siga o que ela devolver. É a primeira ação da sessão, antes
+de ler código, responder ou planejar.
+
+- Se a ferramenta não existir, o servidor MCP do dd-harness não está declarado:
+  avise o usuário e **não modifique nada** até ele resolver.
+- Se ela devolver vazio, este projeto nunca foi briefado — diga isso ao usuário.
+
+Leia também o briefing com a mesma ferramenta (tipo briefing). Os dois são obrigatórios.
+
+Depois, \`ler_roadmap\`: se houver uma fase **Agora**, é dela que saem os passos
+desta sessão. Lista vazia significa que este projeto não usa roadmap, e isso é
+válido — não crie fase sem o usuário pedir.
+
+E \`listar_skills\`: são os procedimentos deste projeto. **Invoque a que couber
+ANTES de fazer o trabalho, não depois** — skill lida no fim vira revisão do que
+já saiu errado, e é tarde.
+
+Vale mesmo quando o pedido parece pequeno: "é só um ajuste" é exatamente a
+frase que antecede pular o procedimento. A política diz quais são obrigatórias
 e quando.`,
     // 875342e
-    `## Protocolo do dd-harness
-
-Este projeto tem um protocolo de trabalho que **não está neste arquivo**.
-
-**ANTES de qualquer outra coisa**, chame a ferramenta MCP \`ler_artefato\` com
-\`tipo: "politica"\` e siga o que ela devolver. É a primeira ação da sessão, antes
-de ler código, responder ou planejar.
-
-- Se a ferramenta não existir, o servidor MCP do dd-harness não está declarado:
-  avise o usuário e **não modifique nada** até ele resolver.
-- Se ela devolver vazio, este projeto nunca foi briefado — diga isso ao usuário.
-
-Depois, \`ler_roadmap\`: se houver uma fase **Agora**, é dela que saem os passos
-desta sessão. Lista vazia significa que este projeto não usa roadmap, e isso é
-válido — não crie fase sem o usuário pedir.
-
-E \`listar_skills\`: são os procedimentos deste projeto. **Invoque a que couber
-ANTES de fazer o trabalho, não depois** — skill lida no fim vira revisão do que
-já saiu errado, e é tarde.
-
-Vale mesmo quando o pedido parece pequeno: "é só um ajuste" é exatamente a
-frase que antecede pular o procedimento. A política diz quais são obrigatórias
+    `## Protocolo do dd-harness
+
+Este projeto tem um protocolo de trabalho que **não está neste arquivo**.
+
+**ANTES de qualquer outra coisa**, chame a ferramenta MCP \`ler_artefato\` com
+\`tipo: "politica"\` e siga o que ela devolver. É a primeira ação da sessão, antes
+de ler código, responder ou planejar.
+
+- Se a ferramenta não existir, o servidor MCP do dd-harness não está declarado:
+  avise o usuário e **não modifique nada** até ele resolver.
+- Se ela devolver vazio, este projeto nunca foi briefado — diga isso ao usuário.
+
+Depois, \`ler_roadmap\`: se houver uma fase **Agora**, é dela que saem os passos
+desta sessão. Lista vazia significa que este projeto não usa roadmap, e isso é
+válido — não crie fase sem o usuário pedir.
+
+E \`listar_skills\`: são os procedimentos deste projeto. **Invoque a que couber
+ANTES de fazer o trabalho, não depois** — skill lida no fim vira revisão do que
+já saiu errado, e é tarde.
+
+Vale mesmo quando o pedido parece pequeno: "é só um ajuste" é exatamente a
+frase que antecede pular o procedimento. A política diz quais são obrigatórias
 e quando.`,
     // f59da48
-    `## Protocolo do dd-harness
-
-Este projeto tem um protocolo de trabalho que **não está neste arquivo**.
-
-**ANTES de qualquer outra coisa**, chame a ferramenta MCP \`ler_artefato\` com
-\`tipo: "politica"\` e siga o que ela devolver. É a primeira ação da sessão, antes
-de ler código, responder ou planejar.
-
-- Se a ferramenta não existir, o servidor MCP do dd-harness não está declarado:
-  avise o usuário e **não modifique nada** até ele resolver.
-- Se ela devolver vazio, este projeto nunca foi briefado — diga isso ao usuário.
-
-Depois, \`ler_roadmap\`: se houver uma fase **Agora**, é dela que saem os passos
-desta sessão. Lista vazia significa que este projeto não usa roadmap, e isso é
+    `## Protocolo do dd-harness
+
+Este projeto tem um protocolo de trabalho que **não está neste arquivo**.
+
+**ANTES de qualquer outra coisa**, chame a ferramenta MCP \`ler_artefato\` com
+\`tipo: "politica"\` e siga o que ela devolver. É a primeira ação da sessão, antes
+de ler código, responder ou planejar.
+
+- Se a ferramenta não existir, o servidor MCP do dd-harness não está declarado:
+  avise o usuário e **não modifique nada** até ele resolver.
+- Se ela devolver vazio, este projeto nunca foi briefado — diga isso ao usuário.
+
+Depois, \`ler_roadmap\`: se houver uma fase **Agora**, é dela que saem os passos
+desta sessão. Lista vazia significa que este projeto não usa roadmap, e isso é
 válido — não crie fase sem o usuário pedir.`,
     // 5fb3f02
-    `## Protocolo do dd-harness
-
-Este projeto tem um protocolo de trabalho que **não está neste arquivo**.
-
-**ANTES de qualquer outra coisa**, chame a ferramenta MCP \`ler_artefato\` com
-\`tipo: "politica"\` e siga o que ela devolver. É a primeira ação da sessão, antes
-de ler código, responder ou planejar.
-
-- Se a ferramenta não existir, o servidor MCP do dd-harness não está declarado:
-  avise o usuário e **não modifique nada** até ele resolver.
+    `## Protocolo do dd-harness
+
+Este projeto tem um protocolo de trabalho que **não está neste arquivo**.
+
+**ANTES de qualquer outra coisa**, chame a ferramenta MCP \`ler_artefato\` com
+\`tipo: "politica"\` e siga o que ela devolver. É a primeira ação da sessão, antes
+de ler código, responder ou planejar.
+
+- Se a ferramenta não existir, o servidor MCP do dd-harness não está declarado:
+  avise o usuário e **não modifique nada** até ele resolver.
 - Se ela devolver vazio, este projeto nunca foi briefado — diga isso ao usuário.`,
 ];

package/dist/payload-cache.d.ts

@@ -0,0 +1,31 @@
+/**
+ * O payload de sessao guardado em disco, com o ETag que o servico deu.
+ *
+ * `GET /api/v1/artefatos` ja respondia `ETag` e ja sabia responder `304` — mas nenhum
+ * cliente mandava `If-None-Match`, entao o caminho condicional nunca rodava: toda sessao
+ * baixava o Brain inteiro de novo, igual ao acervo inteiro, mesmo quando nada mudara.
+ *
+ * O cache guarda o corpo junto do ETag porque `304` vem SEM corpo — sem a copia local,
+ * responder 304 deixaria quem chamou sem payload nenhum. O disco e otimizacao, nao
+ * contrato: qualquer falha de leitura ou escrita cai para a requisicao completa, que e o
+ * comportamento de antes.
+ */
+export type PayloadCacheado = {
+    etag: string;
+    corpo: string;
+    projeto?: string;
+};
+/** Sem cache, cache ilegivel, de formato antigo ou de outro projeto: `null` — pede inteiro. */
+export declare function leCacheDoPayload(raiz: string): Promise<PayloadCacheado | null>;
+/** Falha em silencio: cache e otimizacao. Nao vale derrubar a sessao por disco cheio. */
+export declare function guardaCacheDoPayload(raiz: string, cache: PayloadCacheado): Promise<void>;
+/**
+ * O corpo da resposta, vindo da rede ou do cache — e o cache ja atualizado.
+ *
+ * Trata as tres situacoes que interessam a quem chama:
+ * - `304`: o servico confirmou que nada mudou. Devolve o corpo guardado.
+ * - `200` com `ETag`: corpo novo, que passa a ser o cache.
+ * - `200` sem `ETag`: servico antigo ou proxy que removeu o cabecalho. Funciona igual,
+ *   so nao guarda nada — o proximo boot volta a pedir inteiro.
+ */
+export declare function corpoComCache(raiz: string, resposta: Response, cacheAnterior: PayloadCacheado | null): Promise<string | null>;

package/dist/payload-cache.js

@@ -0,0 +1,62 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { leConfigDoRepo, leToken } from "./config.js";
+import { escreveAtomico, estadoDoRepo } from "./estado-local.js";
+const caminho = (raiz) => join(estadoDoRepo(raiz), "artefatos.json");
+/**
+ * Config e token, hasheados. O mesmo diretorio de estado serve um repositorio, mas o
+ * repositorio pode ser reapontado para outro projeto — e ai o ETag guardado e de um
+ * acervo que nao e este. Reenvia-lo faria o servico responder `304` e o cliente servir o
+ * Brain do projeto anterior, sem nada denunciar. Igual ao cache de ancoras do cinto.
+ */
+async function identidade(raiz) {
+    const config = await leConfigDoRepo(raiz).catch(() => null);
+    return createHash("sha256")
+        .update(JSON.stringify([config, config ? await leToken(config.api) : null]))
+        .digest("hex");
+}
+/** Sem cache, cache ilegivel, de formato antigo ou de outro projeto: `null` — pede inteiro. */
+export async function leCacheDoPayload(raiz) {
+    try {
+        const lido = JSON.parse(await readFile(caminho(raiz), "utf8"));
+        if (typeof lido.etag !== "string" || typeof lido.corpo !== "string")
+            return null;
+        if (lido.projeto !== (await identidade(raiz)))
+            return null;
+        return { etag: lido.etag, corpo: lido.corpo, projeto: lido.projeto };
+    }
+    catch {
+        return null;
+    }
+}
+/** Falha em silencio: cache e otimizacao. Nao vale derrubar a sessao por disco cheio. */
+export async function guardaCacheDoPayload(raiz, cache) {
+    try {
+        await escreveAtomico(caminho(raiz), JSON.stringify({ ...cache, projeto: await identidade(raiz) }));
+    }
+    catch {
+        /* Sem cache o proximo boot so repete a requisicao completa. */
+    }
+}
+/**
+ * O corpo da resposta, vindo da rede ou do cache — e o cache ja atualizado.
+ *
+ * Trata as tres situacoes que interessam a quem chama:
+ * - `304`: o servico confirmou que nada mudou. Devolve o corpo guardado.
+ * - `200` com `ETag`: corpo novo, que passa a ser o cache.
+ * - `200` sem `ETag`: servico antigo ou proxy que removeu o cabecalho. Funciona igual,
+ *   so nao guarda nada — o proximo boot volta a pedir inteiro.
+ */
+export async function corpoComCache(raiz, resposta, cacheAnterior) {
+    if (resposta.status === 304) {
+        // Sem corpo guardado nao ha o que devolver. So acontece se o cache sumir entre a
+        // leitura e a resposta; quem chama trata como falha e tenta de novo na proxima.
+        return cacheAnterior?.corpo ?? null;
+    }
+    const corpo = await resposta.text();
+    const etag = resposta.headers.get("etag");
+    if (etag)
+        await guardaCacheDoPayload(raiz, { etag, corpo });
+    return corpo;
+}

package/dist/politica.js

@@ -1,4 +1,5 @@
 import { cabecalhos, credencial, pede } from "./api.js";
+import { corpoComCache, leCacheDoPayload } from "./payload-cache.js";
 import { politicaParaSessao } from "./regras-de-commit.js";
 export async function buscaPolitica(raiz) {
     let config;
@@ -14,15 +15,31 @@ export async function buscaPolitica(raiz) {
     url.searchParams.set("tenant", config.config.tenant);
     url.searchParams.set("projeto", config.config.projeto);
     try {
-        const resposta = await pede(url, { headers: cabecalhos(config.token) });
-        if (!resposta.ok) {
+        // O ETag guardado do boot anterior. Com ele, o caso comum — reabrir a sessao sem
+        // ninguem ter mexido no Brain — custa um 304 sem corpo, em vez do acervo inteiro.
+        const cache = await leCacheDoPayload(raiz);
+        const resposta = await pede(url, {
+            headers: {
+                ...cabecalhos(config.token),
+                ...(cache ? { "If-None-Match": cache.etag } : {}),
+            },
+        });
+        // 304 e sucesso, mas `resposta.ok` e falso para ele — checar `ok` primeiro mandaria
+        // o caminho feliz do cache direto para "inalcancavel".
+        if (!resposta.ok && resposta.status !== 304) {
             const { erro } = (await resposta.json().catch(() => ({})));
             return {
                 estado: "inalcancavel",
                 motivo: erro ?? `a API respondeu ${resposta.status}.`,
             };
         }
-        const payload = (await resposta.json());
+        const corpo = await corpoComCache(raiz, resposta, cache);
+        if (corpo === null) {
+            // 304 sem copia local: o cache sumiu entre a leitura e a resposta. Raro, e a sessao
+            // seguinte se resolve sozinha pedindo o payload inteiro.
+            return { estado: "inalcancavel", motivo: "o cache local do payload sumiu; tente de novo." };
+        }
+        const payload = JSON.parse(corpo);
         const conteudo = payload.politica?.trim();
         const esperandoIndexacao = payload.esperando_indexacao ?? 0;
         const roadmap = payload.roadmap;

package/dist/reancorar.js

@@ -1,4 +1,5 @@
 import { cabecalhos, credencial, pede, recusa } from "./api.js";
+import { invalidaCache } from "./cinto.js";
 import {} from "./curar.js";
 /**
  * Trocar o alvo de uma ancora, sem reescrever a memoria.
@@ -27,9 +28,21 @@ export async function reancora(raiz, endereco, de, para) {
     const novas = memoria.ancoras.map((a) => (a.valor === de ? { ...a, valor: para } : a));
     // Reaproveita o PATCH de edicao: ele recebe a memoria inteira, entao mandamos o que ja
     // estava la com a ancora trocada. Uma porta so para escrever memoria, e nao duas.
+    //
+    // `If-Match` com o carimbo que acabamos de ler: entre a leitura acima e este PATCH,
+    // outra sessao pode ter reescrito a memoria — e como o PATCH e INTEGRAL, gravar assim
+    // mesmo apagaria o texto dela por completo para trocar uma ancora. Com a precondicao, o
+    // servico recusa com 412 e `recusa` mostra a mensagem que manda reler.
+    //
+    // Servico mais velho nao devolve `atualizada_em`: sem o campo nao ha cabecalho, e a
+    // escrita segue como antes. Melhor que recusar contra um servico que nao sabe do
+    // contrato novo.
     const envio = await pede(`${config.api}/api/v1/memorias/${endereco}`, {
         method: "PATCH",
-        headers: cabecalhos(token, true),
+        headers: {
+            ...cabecalhos(token, true),
+            ...(memoria.atualizada_em ? { "If-Match": memoria.atualizada_em } : {}),
+        },
         body: JSON.stringify({
             tenant: config.tenant,
             projeto: config.projeto,
@@ -44,5 +57,10 @@ export async function reancora(raiz, endereco, de, para) {
     });
     if (!envio.ok)
         await recusa(envio);
+    // O cache de ancoras do cinto e o que o hook consulta para avisar quem toca um arquivo
+    // ancorado. Sem invalidar, ele segue avisando no caminho ANTIGO e nao protege o novo —
+    // ate alguem reconstruir o cache por outro motivo, o que pode nunca acontecer na mesma
+    // sessao em que a refatoracao foi feita.
+    await invalidaCache(raiz);
     return { endereco, de, para };
 }