@daniellins/power-claude 0.16.3

package/scripts/pod-export-tools.cjs

@@ -0,0 +1,470 @@
+'use strict';
+/**
+ * pod-export-tools.cjs — as 4 tools CONFINADAS do executor de fase de PRODUÇÃO (Story SF10.2,
+ * épico pod-export F2). Industrialização de `spike/pod-export-c3/tools.cjs` (PoC 7/7): mesma
+ * contenção que o spike PROVOU, agora como biblioteca de produção com suíte formal.
+ *
+ * ADR-018 Decisão 3 / Adendo F2 DF2-3 estende o modelo de ameaça de ADR-011 ao servidor: a
+ * superfície de execução nova (fetch/imagem/write/read) DEVE ser confinada — sem SSRF, sem
+ * traversal, sem shell. NENHUMA destas tools executa shell. Todas as escritas são confinadas
+ * ao runDir da fase.
+ *
+ * Rede INJETÁVEL (`transport`/`imageTransport`) para testes herméticos de CI (precedente
+ * `pod-export-compile.cjs` `fetchImpl`). Os caminhos de NEGATIVA de segurança (host bloqueado,
+ * fora da whitelist, traversal, path absoluto) fazem short-circuit ANTES de qualquer rede/IO —
+ * são hermeticamente testáveis sem mock.
+ *
+ * Node >= 18, zero dependências externas.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const https = require('node:https');
+const http = require('node:http');
+const crypto = require('node:crypto');
+
+const MAX_FETCH_BYTES = 400 * 1024; // teto de corpo lido (anti-abuso)
+
+// ── Proveniência do run (SF10.8 / ADR-018 Correção 1 do Adendo F5, DF5-6/e1) ──────
+// O veto bloqueante da não-cópia deixou de ser um limiar perceptual (R4 FALSIFICADA) e
+// passou a ser um INVARIANTE DE PROVENIÊNCIA: só passa a etapa cujas imagens em `assets/`
+// foram gravadas pelas TOOLS deste run e cuja referência em `inputs/` está bit-a-bit como
+// o CÓDIGO a materializou. Duas camadas, independentes por construção:
+//   (1) DENYLIST DE ESCRITA — nenhuma tool escreve sob `<runDir>/<RUN_INPUTS_DIRNAME>/`
+//       (`confinedResolveWritable`), fechando o vetor INTEG-1 do gate de QA;
+//   (2) REGISTRO sha256 — toda gravação de bytes por código é registrada num ledger fora
+//       da árvore gravável pelo agente; o veto RECUSA (fail-loud) qualquer divergência.
+// Cada camada segura sozinha: (1) impede o vetor conhecido, (2) detecta a CLASSE inteira
+// (inclusive um caminho de escrita que (1) não tenha antecipado).
+const RUN_INPUTS_DIRNAME = 'inputs';            // convenção FIXA lida pelo veto (`--refs-dir ../inputs`)
+const RUN_ASSETS_DIRNAME = 'assets';            // onde `openrouter_image` grava (única porta de bytes)
+const PROVENANCE_SUFFIX = '.provenance.json';   // ledger = IRMÃO do runDir, nunca DENTRO dele
+const PROVENANCE_VERSION = 1;
+// Extensões consideradas IMAGEM na verificação do lado `assets/` (mesma lista que o veto de medida
+// usa para varrer o diretório): arquivo de texto que uma fase escreva em `assets/` não é objeto
+// deste invariante — só bytes de imagem entram por `openrouter_image`.
+const PROVENANCE_IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp']);
+const PROVENANCE_MAX_DEPTH = 3;                 // varredura determinística e limitada
+
+/**
+ * Path do registro de proveniência de um run: `<runDir>.provenance.json`, IRMÃO do runDir.
+ * Fica fora da árvore gravável pelo agente por CONSTRUÇÃO — `confinedResolve` exige que todo
+ * destino de escrita esteja DENTRO do runDir, e o irmão não está. Não depende da denylist.
+ * Contrato duplicado (deliberadamente) em `scripts/veto-checks/phash-gate.cjs`, que é blessed
+ * e não pode importar este módulo; a suíte assere que as duas pontas concordam.
+ */
+function provenancePathFor(runDir) {
+  return path.resolve(runDir) + PROVENANCE_SUFFIX;
+}
+
+function sha256File(abs) {
+  return crypto.createHash('sha256').update(fs.readFileSync(abs)).digest('hex');
+}
+
+/** Chave do ledger: path relativo ao runDir, sempre em separador POSIX (determinístico). */
+function provenanceKey(runDir, abs) {
+  return path.relative(path.resolve(runDir), path.resolve(abs)).split(path.sep).join('/');
+}
+
+/**
+ * Registra (ou ATUALIZA) o sha256 de um arquivo gravado POR CÓDIGO no ledger do run.
+ * `section` = 'assets' (imagem gravada por `openrouter_image`) | 'inputs' (referência copiada
+ * por `materializeInputs`). Escrita atômica (tmp + rename).
+ *
+ * FAIL-LOUD: ledger existente ilegível/de versão desconhecida LANÇA em vez de sobrescrever —
+ * silenciar aqui reabriria a porta para "resetar" a proveniência de um run.
+ */
+function recordProvenance(runDir, section, absFile, extra = {}) {
+  if (section !== 'assets' && section !== 'inputs') throw new Error(`seção de proveniência inválida: ${section}`);
+  const ledgerPath = provenancePathFor(runDir);
+  const now = new Date().toISOString();
+  let ledger = { version: PROVENANCE_VERSION, run_dir: path.resolve(runDir), created_at: now, updated_at: now, inputs: {}, assets: {}, measures: {} };
+  if (fs.existsSync(ledgerPath)) {
+    let parsed;
+    try { parsed = JSON.parse(fs.readFileSync(ledgerPath, 'utf8')); } catch (e) {
+      throw new Error(`registro de proveniência ilegível (${ledgerPath}): ${e.message} — recusando gravar por cima (fail-loud)`);
+    }
+    if (!parsed || typeof parsed !== 'object' || parsed.version !== PROVENANCE_VERSION) {
+      throw new Error(`registro de proveniência com versão inesperada (${ledgerPath}) — recusando gravar por cima (fail-loud)`);
+    }
+    ledger = {
+      ...ledger, ...parsed,
+      inputs: parsed.inputs && typeof parsed.inputs === 'object' ? parsed.inputs : {},
+      assets: parsed.assets && typeof parsed.assets === 'object' ? parsed.assets : {},
+      measures: parsed.measures && typeof parsed.measures === 'object' ? parsed.measures : {},
+    };
+  }
+  const key = provenanceKey(runDir, absFile);
+  const entry = { sha256: sha256File(absFile), bytes: fs.statSync(absFile).size, at: now, ...extra };
+  ledger[section][key] = entry;
+  ledger.updated_at = now;
+  const tmp = `${ledgerPath}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(ledger, null, 2)}\n`, 'utf8');
+  fs.renameSync(tmp, ledgerPath);
+  return { ledgerPath, key, sha256: entry.sha256 };
+}
+
+// ── Verificação CANÔNICA da proveniência (SF10.19 / ADR-018 Adendo F6-b, DF-SF10.19-2/e2) ──
+//
+// POR QUE ELA VIVE AQUI, e não mais no blessed `phash-gate.cjs` (DF-SF10.19-1 / -4):
+// um veto declarado em `wf-*.yaml` é compartilhado por TODOS os drivers do mesmo yaml — hoje
+// `pc-run-pod.cjs` (dev, subagente com Bash/Write) e `pod-export-executor.cjs` (export, 4 tools
+// confinadas). Uma invariante de ORIGEM só é verificável onde a superfície de tools é confinada:
+// no dev o agente escreve `assets/` por fora de qualquer código de registro e alcança o ledger com
+// shell, então o mesmo verde teria significados diferentes conforme quem rodou (gate-teatro, DF4-5).
+// Logo a checagem passa a viver AO LADO de `recordProvenance` — uma única implementação do contrato
+// do ledger — e é consumida pelo EXECUTOR, que é o componente que garante a premissa.
+//
+// O invariante NÃO muda de força, só de hospedeiro: as duas camadas de INTEG-1 continuam de pé —
+// (1) `confinedResolveWritable` nega escrita sob `inputs/`; (2) esta verificação detecta a CLASSE
+// inteira, inclusive um caminho de escrita que (1) não tenha antecipado.
+
+/** Lista arquivos regulares sob `dir` (recursivo, profundidade limitada), ordenado — determinístico. */
+function listProvenanceFiles(dir, { imagesOnly = false, depth = 0 } = {}) {
+  if (!fs.existsSync(dir) || depth > PROVENANCE_MAX_DEPTH) return [];
+  const out = [];
+  for (const e of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1))) {
+    if (e.name.startsWith('.')) continue;
+    const abs = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...listProvenanceFiles(abs, { imagesOnly, depth: depth + 1 }));
+    else if (e.isFile() && (!imagesOnly || PROVENANCE_IMAGE_EXT.has(path.extname(e.name).toLowerCase()))) out.push(abs);
+  }
+  return out;
+}
+
+/**
+ * Carrega o ledger do run para VERIFICAÇÃO. Devolve `{ ok:false, error }` em ausência/ilegibilidade
+ * /versão desconhecida — NUNCA um registro vazio como se fosse válido (isso passaria a aprovar
+ * qualquer coisa). `exists` distingue "não há ledger" de "há e está quebrado".
+ */
+function loadProvenanceLedger(runDir) {
+  const ledgerPath = provenancePathFor(runDir);
+  if (!fs.existsSync(ledgerPath)) return { ok: false, exists: false, ledgerPath, error: `registro de proveniência AUSENTE em ${ledgerPath}` };
+  let parsed;
+  try { parsed = JSON.parse(fs.readFileSync(ledgerPath, 'utf8')); } catch (e) {
+    return { ok: false, exists: true, ledgerPath, error: `registro de proveniência ILEGÍVEL (${ledgerPath}): ${e.message}` };
+  }
+  if (!parsed || typeof parsed !== 'object' || parsed.version !== PROVENANCE_VERSION) {
+    return { ok: false, exists: true, ledgerPath, error: `registro de proveniência com formato/versão inesperados (${ledgerPath}) — nunca interpretar schema estranho` };
+  }
+  const norm = (o) => (o && typeof o === 'object' ? o : {});
+  return { ok: true, exists: true, ledgerPath, ledger: { ...parsed, inputs: norm(parsed.inputs), assets: norm(parsed.assets), measures: norm(parsed.measures) } };
+}
+
+function isUnderDir(root, abs) {
+  const r = path.resolve(root);
+  const a = path.resolve(abs);
+  return a === r || a.startsWith(r + path.sep);
+}
+
+/**
+ * INVARIANTE DE PROVENIÊNCIA do run (DF5-6/e1, hospedado aqui por DF-SF10.19-2/e2). PURA quanto a
+ * decisão: lê disco e ledger, não escreve nada, não lança. Duas regras, ambas POR-ARQUIVO (DF5-3):
+ *
+ *  1. INTEGRIDADE (nos dois sentidos): todo arquivo sob `<runDir>/inputs/` e toda imagem sob
+ *     `<runDir>/assets/` consta do ledger com sha256 idêntico, E toda entrada do ledger sob esses
+ *     diretórios existe em disco. Nada nos dois diretórios e nada no ledger ⇒ nada a verificar
+ *     (pod sem imagem não passa a exigir ledger — a mudança é INERTE para os outros pods).
+ *  2. NÃO-VACUIDADE (só quando `requireNonVacuous`): a fase que DECLARA o veto de não-cópia tem de
+ *     ter ≥1 referência materializada e ≥1 imagem registrada. É a garantia que o `exit 3` do veto
+ *     dava de graça e que, sem esta regra, sumiria ao script virar medida-only.
+ */
+function checkRunProvenance({ runDir, requireNonVacuous = false, stepId = null }) {
+  const refsAbs = path.join(path.resolve(runDir), RUN_INPUTS_DIRNAME);
+  const assetsAbs = path.join(path.resolve(runDir), RUN_ASSETS_DIRNAME);
+  const refFiles = listProvenanceFiles(refsAbs);
+  const genFiles = listProvenanceFiles(assetsAbs, { imagesOnly: true });
+  const loaded = loadProvenanceLedger(runDir);
+  const violations = [];
+  const fase = stepId ? `a fase "${stepId}"` : 'a fase corrente';
+  // Regra 2 aplicada nos DOIS ramos (com e sem ledger): sem ela, um run sem ledger nenhum devolveria
+  // só "registro ausente" e esconderia que a fase também não produziu nada.
+  const checkNonVacuity = (registeredRefs, registeredAssets) => {
+    if (!requireNonVacuous) return;
+    if (registeredRefs === 0) {
+      violations.push(`${fase} declara o veto de não-cópia, mas NENHUMA referência materializada consta do registro (${refsAbs}) — a referência é copiada POR CÓDIGO pelo executor (materializeInputs a partir de "inputs_dir"); copiá-la à mão não produz proveniência`);
+    }
+    if (registeredAssets === 0) {
+      violations.push(`${fase} declara produzir imagem sob o veto de não-cópia, mas NENHUMA imagem registrada existe em ${assetsAbs} — sem peça gravada por openrouter_image não há proveniência a verificar (etapa não passa por vacuidade)`);
+    }
+  };
+
+  if (!loaded.ok) {
+    // Ledger inválido só é irrelevante quando NÃO há nada para provar e nada é exigido. Um ledger
+    // que EXISTE e está quebrado é sempre violação (fail-loud: nunca gravar/decidir por cima dele).
+    if (loaded.exists || refFiles.length > 0 || genFiles.length > 0 || requireNonVacuous) {
+      violations.push(`${loaded.error} — sem registro íntegro não há como provar que as imagens em ${RUN_ASSETS_DIRNAME}/ foram gravadas pelas tools deste run nem que a referência em ${RUN_INPUTS_DIRNAME}/ está bit-a-bit como o código a materializou`);
+      checkNonVacuity(0, 0);
+      return { ok: false, violations, ledgerPath: loaded.ledgerPath, refs: refFiles.length, assets: genFiles.length, registeredRefs: 0, registeredAssets: 0 };
+    }
+    return { ok: true, violations, ledgerPath: loaded.ledgerPath, refs: 0, assets: 0, registeredRefs: 0, registeredAssets: 0 };
+  }
+
+  const { ledger } = loaded;
+  const checkSide = (dirAbs, files, registry, label) => {
+    for (const abs of files) {
+      const key = provenanceKey(runDir, abs);
+      const entry = registry[key];
+      if (!entry || typeof entry.sha256 !== 'string') {
+        violations.push(`${label} "${key}" NÃO consta do registro de proveniência do run — não foi gravada pelas tools/pelo executor`);
+        continue;
+      }
+      const sha = sha256File(abs);
+      if (sha !== entry.sha256) {
+        violations.push(`${label} "${key}" DIVERGE do sha256 registrado (registro ${entry.sha256.slice(0, 12)}…, disco ${sha.slice(0, 12)}…) — os bytes mudaram depois da gravação por código`);
+      }
+    }
+    let registered = 0;
+    for (const [key, entry] of Object.entries(registry)) {
+      const abs = path.resolve(runDir, key);
+      if (!isUnderDir(dirAbs, abs)) continue; // registrada fora deste diretório: não é objeto desta checagem
+      registered++;
+      if (!fs.existsSync(abs)) violations.push(`${label} registrada "${key}" (sha ${String(entry.sha256).slice(0, 12)}…) AUSENTE em disco`);
+    }
+    return registered;
+  };
+  const registeredRefs = checkSide(refsAbs, refFiles, ledger.inputs, 'referência');
+  const registeredAssets = checkSide(assetsAbs, genFiles, ledger.assets, 'imagem gerada');
+
+  checkNonVacuity(registeredRefs, registeredAssets);
+  return { ok: violations.length === 0, violations, ledgerPath: loaded.ledgerPath, refs: refFiles.length, assets: genFiles.length, registeredRefs, registeredAssets };
+}
+
+/**
+ * A mesma verificação, em forma de ASSERÇÃO fail-loud: LANÇA com mensagem acionável. É o que o
+ * executor chama antes de `motor.advance` — e lançar é o HALT do run (DF-SF10.19-2/e3): violação de
+ * proveniência não é conteúdo que o modelo possa corrigir (sob as 4 tools ela é INALCANÇÁVEL), logo
+ * significa bug de tool, adulteração ou driver novo não-conformante. Consumir tentativa nisso
+ * mascararia a causa — por isso a asserção NÃO devolve um veredito retentável, ela interrompe.
+ */
+function assertRunProvenance({ runDir, requireNonVacuous = false, stepId = null }) {
+  const r = checkRunProvenance({ runDir, requireNonVacuous, stepId });
+  if (r.ok) return r;
+  throw new Error(
+    `PROVENIÊNCIA VIOLADA${stepId ? ` na fase "${stepId}"` : ''} — run HALTADO (sem retentativa): ` +
+    r.violations.join('; ') +
+    `. Registro do run: ${r.ledgerPath}. Nenhuma imagem entra no run sem ter sido produzida pelas tools do run, ` +
+    'e a referência comparada tem de ser bit-a-bit a que o código materializou: grave as peças geradas em ' +
+    `"${RUN_ASSETS_DIRNAME}/" com openrouter_image (escrever em "${RUN_INPUTS_DIRNAME}/" é PROIBIDO) e não altere ` +
+    'arquivos do run por fora das tools. Esta classe de violação é inalcançável pela superfície de tools do ' +
+    'export — se ela aparece, é bug de tool, adulteração ou driver não-conformante, e retentar apenas ' +
+    'mascararia a causa (ADR-018, DF5-6/e1 hospedado no executor por DF-SF10.19-2/e2 e /e3).',
+  );
+}
+
+// ── Segurança de rede: bloqueia hosts privados/loopback/metadata (anti-SSRF) ──────
+// DF2-3: barra INCONDICIONALMENTE, ACIMA da whitelist — mesmo que o host apareça na
+// whitelist, um alvo privado/metadata é recusado (defesa em profundidade contra
+// whitelist mal-configurada pelo operador).
+function isBlockedHost(host) {
+  const h = String(host).toLowerCase().replace(/^\[|\]$/g, ''); // tira colchetes de IPv6 literal
+  if (!h) return true;
+  if (h === 'localhost' || h.endsWith('.local') || h.endsWith('.internal') || h.endsWith('.localhost')) return true;
+  // IPv6 loopback / unspecified / link-local / unique-local.
+  if (h === '::1' || h === '::' || h.startsWith('fe80:') || h.startsWith('fc') || h.startsWith('fd')) return true;
+  // IPv4 privado / loopback / link-local / metadata / unspecified.
+  if (/^(127\.|10\.|192\.168\.|169\.254\.|0\.0\.0\.0)/.test(h)) return true;
+  if (/^172\.(1[6-9]|2[0-9]|3[0-1])\./.test(h)) return true;
+  if (h === '169.254.169.254') return true; // cloud metadata (AWS/GCP/Azure)
+  return false;
+}
+
+/**
+ * Derivação da whitelist de fetch de um run (DF2-3 / AC7): a partir do PAYLOAD DECLARADO
+ * no início do run — NUNCA de uma URL descoberta/sugerida pelo modelo durante a execução.
+ * whitelist = `fetch_allow_hosts` ∪ { host de toda URL http(s) pinada no payload }.
+ * `isBlockedHost` barra por cima disto, incondicionalmente.
+ */
+function computeWhitelist(payload) {
+  const hosts = new Set();
+  const declared = Array.isArray(payload && payload.fetch_allow_hosts) ? payload.fetch_allow_hosts : [];
+  for (const h of declared) if (typeof h === 'string' && h.trim()) hosts.add(h.trim().toLowerCase());
+  // Hosts das URLs pinadas no payload (ex.: article_url). Só top-level string values.
+  for (const [k, v] of Object.entries(payload || {})) {
+    if (k === 'fetch_allow_hosts') continue;
+    if (typeof v !== 'string') continue;
+    if (!/^https?:\/\//i.test(v)) continue;
+    try { hosts.add(new URL(v).hostname.toLowerCase()); } catch { /* URL malformada no payload: ignora (não alarga a whitelist) */ }
+  }
+  return [...hosts];
+}
+
+/** Fetch confinado por WHITELIST de hosts + bloqueio de hosts privados. Sem redirect cego. */
+function httpFetch(url, { whitelistHosts = [], maxBytes = MAX_FETCH_BYTES, transport = null, _redirects = 0 } = {}) {
+  return new Promise((resolve) => {
+    let u;
+    try { u = new URL(url); } catch { return resolve({ ok: false, error: `URL inválida: ${url}` }); }
+    if (u.protocol !== 'https:' && u.protocol !== 'http:') return resolve({ ok: false, error: `protocolo não permitido: ${u.protocol}` });
+    // Ordem deliberada: bloqueio de host privado/metadata ANTES da whitelist (DF2-3).
+    if (isBlockedHost(u.hostname)) return resolve({ ok: false, error: `host bloqueado (privado/loopback/metadata): ${u.hostname}` });
+    const wl = whitelistHosts.map((h) => String(h).toLowerCase());
+    if (wl.length && !wl.includes(u.hostname.toLowerCase())) {
+      return resolve({ ok: false, error: `host fora da whitelist: ${u.hostname} (permitidos: ${wl.join(', ')})` });
+    }
+    // Rede injetável (CI): transport recebe a URL JÁ VALIDADA e devolve o corpo.
+    if (transport) {
+      Promise.resolve(transport(u.toString(), { whitelistHosts: wl, maxBytes })).then(resolve).catch((e) => resolve({ ok: false, error: String(e && e.message || e) }));
+      return;
+    }
+    if (_redirects > 5) return resolve({ ok: false, error: 'excesso de redirects' });
+    const lib = u.protocol === 'https:' ? https : http;
+    const req = lib.get(u, { timeout: 20000, headers: { 'user-agent': 'pod-export-executor/1 (power-claude)' } }, (res) => {
+      // redirect: só segue se o destino também passa a MESMA validação (nunca redirect cego → SSRF).
+      if ([301, 302, 303, 307, 308].includes(res.statusCode) && res.headers.location) {
+        res.resume();
+        const next = new URL(res.headers.location, u).toString();
+        return resolve(httpFetch(next, { whitelistHosts, maxBytes, _redirects: _redirects + 1 }));
+      }
+      let buf = Buffer.alloc(0);
+      res.on('data', (d) => { if (buf.length < maxBytes) buf = Buffer.concat([buf, d]); });
+      res.on('end', () => resolve({ ok: true, status: res.statusCode, contentType: res.headers['content-type'] || '', body: buf.slice(0, maxBytes).toString('utf8'), bytes: buf.length }));
+    });
+    req.on('timeout', () => { req.destroy(); resolve({ ok: false, error: 'timeout' }); });
+    req.on('error', (e) => resolve({ ok: false, error: e.message }));
+  });
+}
+
+// ── Escrita confinada ao runDir (anti-traversal) ─────────────────────────────────
+function confinedResolve(runDir, relPath) {
+  if (typeof relPath !== 'string' || relPath.trim() === '') throw new Error('path vazio');
+  if (path.isAbsolute(relPath)) throw new Error(`path absoluto proibido: ${relPath}`);
+  const abs = path.resolve(runDir, relPath);
+  const root = path.resolve(runDir);
+  if (abs !== root && !abs.startsWith(root + path.sep)) throw new Error(`traversal fora do runDir: ${relPath}`);
+  return abs;
+}
+
+/**
+ * CAMADA 1 de INTEG-1 (SF10.8 / DF5-7 emenda a DF5-1): resolve um destino de ESCRITA.
+ * Tudo que `confinedResolve` já barra (path absoluto, traversal para fora do runDir) MAIS a
+ * DENYLIST de `<runDir>/<RUN_INPUTS_DIRNAME>/` — a árvore onde o EXECUTOR materializa a
+ * referência do run. Sem isso, `openrouter_image(out_path:"inputs/<referência>")` sobrescrevia
+ * a referência comparada com uma imagem recém-gerada e derrotava o veto inteiro (achado INTEG-1
+ * do gate de QA, `docs/qa/gates/sf10.8.yaml`).
+ *
+ * A comparação do primeiro segmento é CASE-INSENSITIVE de propósito: em filesystem
+ * case-insensitive (macOS por default) `INPUTS/ref.png` alcança o MESMO arquivo, e uma
+ * comparação sensível a caixa deixaria o vetor aberto no ambiente de desenvolvimento.
+ *
+ * O registro de proveniência não precisa de regra aqui: ele é IRMÃO do runDir, e `confinedResolve`
+ * já recusa qualquer destino fora do runDir.
+ */
+function confinedResolveWritable(runDir, relPath) {
+  const abs = confinedResolve(runDir, relPath);
+  const rel = path.relative(path.resolve(runDir), abs);
+  const first = rel.split(path.sep)[0] || '';
+  if (first.toLowerCase() === RUN_INPUTS_DIRNAME.toLowerCase()) {
+    throw new Error(
+      `escrita PROIBIDA sob "${RUN_INPUTS_DIRNAME}/": ${relPath}. Esse diretório guarda a REFERÊNCIA ` +
+      'do run, materializada por CÓDIGO (executor) e comparada pelo veto de não-cópia — nenhuma tool ' +
+      'escreve nele. Grave imagens geradas em "assets/".',
+    );
+  }
+  return abs;
+}
+
+function writeFile(relPath, content, { runDir }) {
+  const abs = confinedResolveWritable(runDir, relPath);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, typeof content === 'string' ? content : String(content), 'utf8');
+  return { ok: true, path: path.relative(runDir, abs), bytes: Buffer.byteLength(content || '') };
+}
+
+/**
+ * read_image (AC5 / Achado 4 do spike): confirma/lê imagem confinada.
+ *   - Referência PINADA (`inputs:<nome>`): devolve base64 para leitura MULTIMODAL (o modelo
+ *     PRECISA ver a referência de estilo). Confinada a inputsDir.
+ *   - Imagem GERADA (path relativo ao runDir): confirma por PATH + TAMANHO, NUNCA devolve o
+ *     base64 completo de volta ao modelo (evita inflar o contexto — Achado 4). Mecaniza AC5.
+ */
+function readImage(ref, { runDir, inputsDir }) {
+  if (typeof ref !== 'string' || ref.trim() === '') return { ok: false, error: 'ref vazia' };
+  if (ref.startsWith('inputs:')) {
+    if (!inputsDir) return { ok: false, error: 'inputsDir não configurado para este run (nenhum input pinado)' };
+    const rel = ref.slice('inputs:'.length);
+    if (path.isAbsolute(rel)) return { ok: false, error: `path absoluto proibido em inputs: ${rel}` };
+    const abs = path.resolve(inputsDir, rel);
+    const root = path.resolve(inputsDir);
+    if (abs !== root && !abs.startsWith(root + path.sep)) return { ok: false, error: `leitura fora de inputs/: ${rel}` };
+    if (!fs.existsSync(abs)) return { ok: false, error: `imagem de referência não encontrada: ${ref}` };
+    const buf = fs.readFileSync(abs);
+    const ext = path.extname(abs).slice(1).toLowerCase();
+    const mediaType = ext === 'jpg' ? 'image/jpeg' : `image/${ext || 'png'}`;
+    return { ok: true, kind: 'reference', base64: buf.toString('base64'), mediaType, bytes: buf.length };
+  }
+  // Imagem gerada/escrita no runDir: confirmação por path+tamanho, SEM base64 (Achado 4).
+  let abs;
+  try { abs = confinedResolve(runDir, ref); } catch (e) { return { ok: false, error: e.message }; }
+  if (!fs.existsSync(abs)) return { ok: false, error: `imagem gerada não encontrada: ${ref}` };
+  const bytes = fs.statSync(abs).size;
+  return { ok: true, kind: 'generated', path: path.relative(runDir, abs), bytes };
+}
+
+/**
+ * Geração de imagem via OpenRouter (POST chat/completions, image modality). Escreve PNG
+ * confinado ao runDir. Modelo PINADO passado pelo caller (do bundle). Rede injetável
+ * (`imageTransport`) para CI. Chave lida em runtime pelo caller, nunca gravada.
+ */
+function openrouterImage(prompt, outRel, { runDir, model, apiKey, imageTransport = null }) {
+  return new Promise((resolve) => {
+    if (!model) return resolve({ ok: false, error: 'modelo de imagem ausente (deve vir PINADO do bundle)' });
+    // Resolve/valida o destino ANTES de qualquer rede (anti-traversal + denylist de inputs/).
+    let abs;
+    try { abs = confinedResolveWritable(runDir, outRel); } catch (e) { return resolve({ ok: false, error: e.message }); }
+    const finish = (raw) => {
+      try {
+        const j = typeof raw === 'string' ? JSON.parse(raw) : raw;
+        if (j.error) return resolve({ ok: false, error: `openrouter: ${j.error.message || JSON.stringify(j.error)}` });
+        const msg = j.choices && j.choices[0] && j.choices[0].message;
+        let dataUrl = null;
+        if (msg && Array.isArray(msg.images) && msg.images[0]) dataUrl = msg.images[0].image_url ? msg.images[0].image_url.url : msg.images[0].url;
+        if (!dataUrl && msg && typeof msg.content === 'string') { const m = msg.content.match(/data:image\/[^;]+;base64,[A-Za-z0-9+/=]+/); if (m) dataUrl = m[0]; }
+        if (!dataUrl) return resolve({ ok: false, error: 'resposta sem imagem (modelo não retornou modality image)' });
+        const b64 = dataUrl.split(',')[1];
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, Buffer.from(b64, 'base64'));
+        // CAMADA 2 de INTEG-1 (DF5-6/e1): esta é a ÚNICA porta por onde bytes de imagem entram
+        // no run — registrar aqui o sha256 é o que torna "imagem sem proveniência" detectável.
+        // Falha de registro é FAIL-LOUD (a imagem existe mas não fica registrada ⇒ o veto vai
+        // bloquear; devolver ok:true aqui esconderia a causa do bloqueio adiante).
+        try {
+          recordProvenance(runDir, 'assets', abs, { source: 'openrouter_image', model });
+        } catch (e) {
+          return resolve({ ok: false, error: `imagem escrita em ${path.relative(runDir, abs)} mas NÃO registrada na proveniência do run: ${e.message}` });
+        }
+        // Confirmação por PATH + TAMANHO (Achado 4): nunca devolve o base64 ao modelo.
+        resolve({ ok: true, path: path.relative(runDir, abs), bytes: fs.statSync(abs).size, model });
+      } catch (e) { resolve({ ok: false, error: `parse: ${e.message}` }); }
+    };
+    const payload = { model, messages: [{ role: 'user', content: prompt }], modalities: ['image', 'text'] };
+    if (imageTransport) {
+      Promise.resolve(imageTransport(payload, { apiKey })).then(finish).catch((e) => resolve({ ok: false, error: String(e && e.message || e) }));
+      return;
+    }
+    if (!apiKey) return resolve({ ok: false, error: 'OPENROUTER_API_KEY ausente — parar, nunca substituir (regra de ouro do pod)' });
+    const body = JSON.stringify(payload);
+    const req = https.request('https://openrouter.ai/api/v1/chat/completions', {
+      method: 'POST', timeout: 90000,
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}`, 'content-length': Buffer.byteLength(body) },
+    }, (res) => {
+      let s = '';
+      res.on('data', (d) => { s += d; });
+      res.on('end', () => finish(s));
+    });
+    req.on('timeout', () => { req.destroy(); resolve({ ok: false, error: 'timeout openrouter' }); });
+    req.on('error', (e) => resolve({ ok: false, error: e.message }));
+    req.write(body); req.end();
+  });
+}
+
+module.exports = {
+  httpFetch, writeFile, readImage, openrouterImage,
+  confinedResolve, confinedResolveWritable,
+  isBlockedHost, computeWhitelist, MAX_FETCH_BYTES,
+  // Proveniência (SF10.8 / DF5-6 e1) — o par de máquina do veto de não-cópia.
+  provenancePathFor, recordProvenance, sha256File, provenanceKey,
+  // Verificação CANÔNICA (SF10.19 / DF-SF10.19-2 e2, -4): implementação ÚNICA do contrato do
+  // ledger, consumida pelo executor. O blessed `phash-gate.cjs` não a duplica mais.
+  loadProvenanceLedger, checkRunProvenance, assertRunProvenance, listProvenanceFiles,
+  RUN_INPUTS_DIRNAME, RUN_ASSETS_DIRNAME, PROVENANCE_SUFFIX, PROVENANCE_VERSION, PROVENANCE_IMAGE_EXT,
+};