@daniellins/power-claude 0.16.3

package/scripts/veto-checks/phash-gate.cjs

@@ -0,0 +1,589 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * phash-gate.cjs — script BLESSED (forma command_check, ADR-011) de MEDIDA da não-cópia.
+ * Story SF10.8 (origem) → **Story SF10.19 / ADR-018 Adendo F6-b (DF-SF10.19-1/-2)**, que tirou
+ * daqui a metade bloqueante. / ADR-015 Decisão 3.
+ *
+ * ┌─ ESTE SCRIPT NÃO BLOQUEIA NADA POR CONTEÚDO — E NÃO PODE VOLTAR A BLOQUEAR ────────────┐
+ * │ Ele MEDE e REPORTA. Nenhum estado de insumo (referência ausente, `assets/` vazio,      │
+ * │ ledger ausente/ilegível/de versão desconhecida, sha divergente, Chrome ausente) produz │
+ * │ exit não-zero: todos viram `measure.status` DECLARADO, com o motivo, no bloco do        │
+ * │ artefato e no ledger quando ele existir. O único exit não-zero que resta é 2 —          │
+ * │ uso/config inválida (artefato inexistente, `--refs-dir`/`--assets-dir` escapando do     │
+ * │ runDir): erro de WIRING, idêntico nos dois drivers, nunca julgamento de conteúdo.      │
+ * └───────────────────────────────────────────────────────────────────────────────────────┘
+ *
+ * ┌─ ONDE FOI PARAR O QUE BLOQUEAVA (o invariante NÃO foi afrouxado) ──────────────────────┐
+ * │ A PROVENIÊNCIA (`DF5-6/e1`) continua bloqueando, agora no `pod-export-executor.cjs`     │
+ * │ (`tools.assertRunProvenance`, antes de `motor.advance`) — HALT do run, sem retentativa. │
+ * │ POR QUÊ: este arquivo é executado a partir de um `wf-*.yaml`, e o MESMO yaml é consumido│
+ * │ por dois drivers — `pc-run-pod.cjs` (dev: subagente com Bash/Write) e o executor (export│
+ * │ 4 tools confinadas). Proveniência é uma invariante de ORIGEM: ela só é verificável onde │
+ * │ a superfície de tools é confinada. No dev, o agente grava `assets/` por fora de qualquer│
+ * │ registro e alcança o ledger com shell — o mesmo verde teria significado DIFERENTE       │
+ * │ conforme quem rodou, que é gate-teatro (`DF4-5`). Régua permanente (`DF-SF10.19-1`):    │
+ * │   • propriedade do ARTEFATO/disco (verificável independentemente de quem produziu)      │
+ * │     → PODE viver no wf, e nunca degrada em nenhum driver;                               │
+ * │   • invariante de ORIGEM/CONFINAMENTO → vive no componente que CONFINA, nunca no wf.    │
+ * │ Esta mudança é INCONDICIONAL: não existe flag, env var, campo de modo nem ramo          │
+ * │ "dev vs export" aqui — quem passa a bloquear é um componente que só existe no export.   │
+ * └───────────────────────────────────────────────────────────────────────────────────────┘
+ *
+ * ┌─ O QUE ELE FAZ: SIMILARIDADE (medida REPORTADA, sem pass/fail) ────────────────────────┐
+ * │ A distância perceptual peça↔referência é calculada e GRAVADA (no ledger e num bloco     │
+ * │ delimitado do artefato) para INSTRUMENTAR o checkpoint humano de `assembly`.            │
+ * │ Não há limiar: a não-cópia por ADERÊNCIA ESTILÍSTICA é julgamento HUMANO. E o bloco     │
+ * │ DECLARA o que não foi verificado — no driver de dev, a proveniência não é verificada    │
+ * │ por ninguém, e omitir isso seria pior que não medir (`DF-SF10.19-3`).                   │
+ * └───────────────────────────────────────────────────────────────────────────────────────┘
+ *
+ * POR QUE MUDOU (registro da falsificação, não escondê-la — DF5-5): a versão anterior deste
+ * script bloqueava por "distância de Hamming <= 10/64 = cópia". O gate adversarial do QA
+ * (`docs/qa/gates/sf10.8.yaml`, CAL-1) e as medições próprias do architect mostraram que
+ * (a) NENHUM limiar separa as classes em conteúdo real (capa legítima independente = 10
+ * BLOQUEAVA; cópia fiel reenquadrada 4:5 = 12 PASSAVA; o cover-crop com âncora deslocada mede
+ * 32-36, dentro da massa legítima), em 5 primitivas medidas; e (b) mais decisivo: a classe
+ * "cópia pixel-a-pixel" contra a qual o limiar foi calibrado é INALCANÇÁVEL pela superfície de
+ * tools — `write_file` grava utf8 e a única escrita de bytes é `openrouter_image`, cujo
+ * conteúdo vem da API. Um limiar contra ameaça impossível é teatro (vedado por DF4-5).
+ *
+ * NO EXPORT, os dois lados são materializados POR CÓDIGO, nenhum atestado pelo agente (DF5-1):
+ *   - geradas:    `<runDir>/assets/**` — escritas pela tool `openrouter_image`, que REGISTRA
+ *                 o sha256 de cada gravação;
+ *   - referência: `<runDir>/inputs/**` — copiada do `inputs_dir` do run pelo EXECUTOR
+ *                 (`materializeInputs`), que também REGISTRA o sha256; e as tools NEGAM
+ *                 escrita sob `inputs/` (camada 1 de INTEG-1).
+ * NO DEV nada disso existe (o motor é cego ao `inputs_dir` e o agente escreve com Bash/Write) —
+ * por isso a medida degrada declarada em vez de bloquear, e o bloco diz o que não foi verificado.
+ * Os diretórios chegam como ARGS LITERAIS FIXOS relativos ao diretório do artefato
+ * (`--refs-dir ../inputs`, `--assets-dir ../assets`) — nenhum dado de run é interpolado no
+ * wf.yaml (ADR-011 preservado); o `runDir` é derivado do `artifactPath` que o `command_check`
+ * já passa (invariante `runDir/artifacts/<step>.md`).
+ *
+ * ZERO-DEP npm: a MEDIDA reportada reusa o headless Chrome que o
+ * `render-gate.cjs` já tornou dependência v1 (mesmo `execFileSync` sem shell, mesmo
+ * `probeChrome`, mesmo marcador lido do `--dump-dom`): `<canvas>` + `getImageData` devolvem um
+ * grayscale 32×32 por imagem e o hash perceptual (DCT 2D → bloco 8×8 → mediana → 64 bits) é
+ * aritmética em JS PURO aqui dentro. Nenhuma lib npm, nenhuma ferramenta de ops nova.
+ *
+ * FAIL-LOUD sem virar gate: como este script não decide mais nada, "pular" não é um risco dele —
+ * o risco é ele MENTIR por omissão. Por isso toda degradação é DECLARADA (status + motivo) no
+ * artefato e no ledger; nada é silencioso, e nada vira exit não-zero (ADR-011 D3 vale para o
+ * componente que É gate, e esse componente agora é o executor).
+ *
+ * POR-ARQUIVO (DF5-3, VIGENTE): a asserção do executor é por-arquivo; aqui a medida é por-peça.
+ *
+ * LIMITES HONESTOS (o que este script NÃO faz):
+ *   - NÃO mecaniza a não-cópia por ADERÊNCIA ESTILÍSTICA (ressíntese generativa que "adere
+ *     demais" à referência): isso permanece julgamento HUMANO no checkpoint de `assembly`,
+ *     agora instrumentado pela medida reportada. Mecanizar essa classe exige corpus rotulado
+ *     por humano — é épico próprio (COMPLEX 19/25, DF5-8);
+ *   - a medida perceptual mede layout grosseiro de luminância; NÃO é plágio jurídico, não é
+ *     invariante a rotação/espelhamento, e não separa classes (por isso não é gate);
+ *   - NÃO verifica proveniência (quem verifica é o executor de export; no driver de dev
+ *     ninguém verifica — o bloco de medida diz isso por extenso, DF-SF10.19-3).
+ *
+ * Uso: node scripts/veto-checks/phash-gate.cjs <artefato> [--refs-dir ../inputs]
+ *      [--assets-dir ../assets]        (args de CLI INALTERADOS — bundles já compilados seguem válidos)
+ * Exit 0 = medida gravada ou declarada ausente/não-verificada (SEMPRE, em qualquer estado de
+ * insumo); 2 = uso/config inválida (artefato inexistente, dir escapando do runDir). Não há
+ * outro exit: 1 e 3 foram REMOVIDOS junto com a metade bloqueante (DF-SF10.19-2/e1).
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const CHROME_CANDIDATES = [
+  'google-chrome-stable', 'google-chrome', 'chromium', 'chromium-browser', 'chrome',
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+];
+const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp']);
+const SIDE = 32;          // grayscale normalizado 32×32 (entrada da DCT)
+const LOW = 8;            // bloco 8×8 de baixa frequência → 64 bits
+const MAX_TOTAL_BYTES = 48 * 1024 * 1024; // teto de material embutido no HTML temporário
+const MAX_WALK_DEPTH = 3;
+
+// PATH do registro de proveniência. Este script é BLESSED (fronteira `command_check`, ADR-011 D2)
+// e não importa nada além de builtins — um require para fora de `veto-checks/` alargaria a
+// superfície do blessed. Depois da SF10.19 o que sobrou aqui é só o ENDEREÇO do ledger (para
+// gravar a MEDIDA nele quando ele existir); a VERIFICAÇÃO do contrato vive uma única vez em
+// `pod-export-tools.cjs` (DF-SF10.19-4). A suíte assere que as duas pontas concordam no path.
+const PROVENANCE_SUFFIX = '.provenance.json';
+const PROVENANCE_VERSION = 1;
+
+// Delimitadores do bloco de MEDIDA REPORTADA escrito no artefato (idempotente: reescrito, nunca
+// duplicado). Comentário HTML: invisível no render, inerte para os vetos de texto do motor.
+const MEASURE_BEGIN = '<!-- pc:medida-similaridade:inicio -->';
+const MEASURE_END = '<!-- pc:medida-similaridade:fim -->';
+
+/** Testa se um candidato é um Chrome utilizável (idem render-gate.cjs). */
+function usable(cand) {
+  try {
+    if (cand.includes('/')) return fs.existsSync(cand) ? cand : null;
+    execFileSync(cand, ['--version'], { stdio: 'ignore', timeout: 8000 });
+    return cand;
+  } catch { return null; }
+}
+
+/**
+ * Resolve um binário de Chrome utilizável, ou null (→ fail-loud no chamador).
+ * CHROME_BIN setado é honrado ESTRITAMENTE: inválido → null, SEM fallback silencioso.
+ */
+function probeChrome() {
+  if (process.env.CHROME_BIN) return usable(process.env.CHROME_BIN);
+  for (const cand of CHROME_CANDIDATES) {
+    const u = usable(cand);
+    if (u) return u;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Hash perceptual (JS puro, testável sem Chrome).
+// ---------------------------------------------------------------------------
+
+const COS = (() => {
+  // COS[u][x] = cos((2x+1)·u·π / 2N) — pré-computado para a DCT-II separável.
+  const t = [];
+  for (let u = 0; u < SIDE; u++) {
+    const row = new Float64Array(SIDE);
+    for (let x = 0; x < SIDE; x++) row[x] = Math.cos(((2 * x + 1) * u * Math.PI) / (2 * SIDE));
+    t.push(row);
+  }
+  return t;
+})();
+
+/** DCT-II 2D (separável) de uma matriz SIDE×SIDE achatada. */
+function dct2(gray) {
+  const tmp = new Float64Array(SIDE * SIDE);
+  for (let y = 0; y < SIDE; y++) {
+    for (let u = 0; u < LOW; u++) { // só as colunas de baixa frequência são necessárias
+      let s = 0;
+      const cu = COS[u];
+      for (let x = 0; x < SIDE; x++) s += gray[y * SIDE + x] * cu[x];
+      tmp[y * SIDE + u] = s;
+    }
+  }
+  const out = new Float64Array(LOW * LOW);
+  for (let u = 0; u < LOW; u++) {
+    for (let v = 0; v < LOW; v++) {
+      let s = 0;
+      const cv = COS[v];
+      for (let y = 0; y < SIDE; y++) s += tmp[y * SIDE + u] * cv[y];
+      out[v * LOW + u] = s;
+    }
+  }
+  return out;
+}
+
+/**
+ * Hash perceptual de 64 bits a partir do grayscale 32×32: DCT-II → bloco 8×8 de baixa
+ * frequência → bit = coeficiente > MEDIANA (mediana calculada SEM o termo DC, que carrega
+ * só o brilho médio). Invariante a offset de brilho e a ganho de contraste (o que dá a
+ * robustez a recolor/exposição); sensível à ESTRUTURA. Retorna hex de 16 chars.
+ */
+function hashFromGray(gray) {
+  if (!gray || gray.length !== SIDE * SIDE) throw new Error(`grayscale deve ter ${SIDE * SIDE} amostras (recebeu ${gray ? gray.length : 'nada'})`);
+  const c = dct2(gray);
+  const vals = [];
+  for (let i = 1; i < LOW * LOW; i++) vals.push(c[i]); // exclui DC (i=0)
+  vals.sort((a, b) => a - b);
+  const mid = vals.length >> 1;
+  const median = vals.length % 2 ? vals[mid] : (vals[mid - 1] + vals[mid]) / 2;
+  let hex = '';
+  for (let nib = 0; nib < 16; nib++) {
+    let v = 0;
+    for (let b = 0; b < 4; b++) {
+      const i = nib * 4 + b;
+      v = (v << 1) | (c[i] > median ? 1 : 0);
+    }
+    hex += v.toString(16);
+  }
+  return hex;
+}
+
+const POPCOUNT = (() => { const t = new Uint8Array(256); for (let i = 0; i < 256; i++) t[i] = (i & 1) + t[i >> 1]; return t; })();
+
+/** Distância de Hamming entre dois hashes hex de 64 bits. */
+function hamming(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string' || a.length !== 16 || b.length !== 16) {
+    throw new Error('hashes devem ser hex de 16 chars (64 bits)');
+  }
+  let d = 0;
+  for (let i = 0; i < 16; i += 2) {
+    d += POPCOUNT[(parseInt(a.slice(i, i + 2), 16) ^ parseInt(b.slice(i, i + 2), 16)) & 0xFF];
+  }
+  return d;
+}
+
+// ---------------------------------------------------------------------------
+// Decodificação via headless Chrome (canvas + getImageData).
+// ---------------------------------------------------------------------------
+
+/**
+ * Página de medição: decodifica cada imagem embutida (data: URL — NÃO tainta o canvas e
+ * dispensa flags de acesso a arquivo), reduz para SIDE×SIDE por downscale do próprio
+ * navegador, converte para luminância (Rec. 601) e publica tudo num marcador HEX no
+ * documentElement. Zera o corpo ao final para que o --dump-dom volte pequeno.
+ */
+function measurePage(items) {
+  const payload = JSON.stringify(items.map((it) => ({ n: it.id, d: `data:${it.mediaType};base64,${it.base64}` })));
+  return `<!doctype html><html><head><meta charset="utf-8"></head><body>
+<script id="pl" type="application/json">${payload}</script>
+<script>(function(){
+  var SIDE=${SIDE};
+  function fail(msg){
+    try{ document.body.textContent=''; }catch(e){}
+    document.documentElement.setAttribute('data-phash-gate','ERR;'+String(msg).replace(/[^\\w .:\\/-]/g,' ').slice(0,300));
+  }
+  try{
+    var items=JSON.parse(document.getElementById('pl').textContent);
+    var cv=document.createElement('canvas'); cv.width=SIDE; cv.height=SIDE;
+    var cx=cv.getContext('2d',{willReadFrequently:true});
+    cx.imageSmoothingEnabled=true; cx.imageSmoothingQuality='high';
+    var out=[];
+    var pending=items.length, failed=false;
+    if(pending===0){ fail('nenhuma imagem recebida'); return; }
+    items.forEach(function(it,idx){
+      var img=new Image();
+      img.onload=function(){
+        try{
+          cx.clearRect(0,0,SIDE,SIDE);
+          cx.drawImage(img,0,0,SIDE,SIDE);
+          var d=cx.getImageData(0,0,SIDE,SIDE).data, hex='';
+          for(var p=0;p<SIDE*SIDE;p++){
+            var l=Math.round(0.299*d[p*4]+0.587*d[p*4+1]+0.114*d[p*4+2]);
+            if(l<0)l=0; if(l>255)l=255;
+            hex+=(l<16?'0':'')+l.toString(16);
+          }
+          out[idx]=it.n+':'+hex;
+        }catch(e){ failed=true; fail('getImageData falhou em '+it.n+': '+e.message); return; }
+        if(--pending===0 && !failed){
+          document.body.textContent='';
+          document.documentElement.setAttribute('data-phash-gate','OK;'+out.join('|'));
+        }
+      };
+      img.onerror=function(){ failed=true; fail('imagem ilegivel/nao decodificada: '+it.n); };
+      img.src=it.d;
+    });
+  }catch(e){ fail('medicao falhou: '+e.message); }
+})();</script>
+</body></html>`;
+}
+
+/** Lê o marcador do DOM renderizado e devolve { ok, gray: Map<id, Uint8Array>, error }. */
+function parseMarker(domHtml) {
+  const m = String(domHtml).match(/data-phash-gate="([^"]*)"/);
+  if (!m) return { ok: false, error: 'marcador de medição ausente no DOM renderizado (a decodificação não concluiu?)' };
+  const raw = m[1];
+  if (raw.startsWith('ERR;')) return { ok: false, error: raw.slice(4) };
+  if (!raw.startsWith('OK;')) return { ok: false, error: `marcador inesperado: "${raw.slice(0, 80)}"` };
+  const gray = new Map();
+  for (const part of raw.slice(3).split('|')) {
+    const i = part.indexOf(':');
+    if (i < 0) return { ok: false, error: `entrada de medição malformada: "${part.slice(0, 40)}"` };
+    const id = part.slice(0, i);
+    const hex = part.slice(i + 1);
+    if (hex.length !== SIDE * SIDE * 2) return { ok: false, error: `grayscale de "${id}" com tamanho inesperado (${hex.length} chars)` };
+    const arr = new Uint8Array(SIDE * SIDE);
+    for (let p = 0; p < arr.length; p++) arr[p] = parseInt(hex.slice(p * 2, p * 2 + 2), 16);
+    gray.set(id, arr);
+  }
+  return { ok: true, gray };
+}
+
+function mediaTypeOf(p) {
+  const e = path.extname(p).slice(1).toLowerCase();
+  if (e === 'jpg' || e === 'jpeg') return 'image/jpeg';
+  if (e === 'svg') return 'image/svg+xml';
+  return `image/${e || 'png'}`;
+}
+
+/**
+ * Decodifica TODAS as imagens numa ÚNICA invocação de Chrome (uma etapa = poucas peças).
+ * Retorna Map<id, Uint8Array(1024)> ou lança Error (→ fail-loud no chamador).
+ */
+function grayscalesViaChrome(chromeBin, files) {
+  let total = 0;
+  const items = files.map((f) => {
+    const buf = fs.readFileSync(f.abs);
+    total += buf.length;
+    return { id: f.id, mediaType: mediaTypeOf(f.abs), base64: buf.toString('base64') };
+  });
+  if (total > MAX_TOTAL_BYTES) {
+    throw new Error(`material de imagem excede ${Math.round(MAX_TOTAL_BYTES / 1048576)}MB (${Math.round(total / 1048576)}MB) — recuse em vez de arriscar medição parcial`);
+  }
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-phash-gate-'));
+  const tmpHtml = path.join(tmpDir, 'measure.html');
+  try {
+    fs.writeFileSync(tmpHtml, measurePage(items), 'utf8');
+    const dom = execFileSync(chromeBin, [
+      '--headless=new', '--disable-gpu', '--no-sandbox', '--hide-scrollbars',
+      '--window-size=64,64', '--virtual-time-budget=20000',
+      '--dump-dom', `file://${tmpHtml}`,
+    ], { encoding: 'utf8', timeout: 60000, maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+    const r = parseMarker(dom);
+    if (!r.ok) throw new Error(r.error);
+    for (const f of files) if (!r.gray.has(f.id)) throw new Error(`medição não retornou a imagem "${f.id}"`);
+    return r.gray;
+  } finally {
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { /* best-effort */ }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Coleta de arquivos e veredito.
+// ---------------------------------------------------------------------------
+
+/** Lista imagens sob `dir` (recursivo, profundidade limitada), ordenadas — determinístico. */
+function listImages(dir, depth = 0) {
+  if (!fs.existsSync(dir) || depth > MAX_WALK_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(...listImages(abs, depth + 1));
+    else if (e.isFile() && IMAGE_EXT.has(path.extname(e.name).toLowerCase())) out.push(abs);
+  }
+  return out;
+}
+
+/**
+ * MEDIDA REPORTADA (e2 de DF5-6), NÃO veredito: para CADA peça gerada, a MENOR distância
+ * perceptual a QUALQUER referência. Sem limiar, sem pass/fail — quem julga "aderiu demais" é
+ * o humano no checkpoint de `assembly`. Pura e testável sem Chrome.
+ *
+ * A função ANTERIOR (`decide`, que bloqueava em distância <= N) foi REMOVIDA junto com o
+ * limiar: mantê-la exportada convidaria a reintroduzir por engano o veredito falsificado.
+ */
+function measureDistances(generated, refs) {
+  return generated.map((g) => {
+    let best = { ref: null, distance: Infinity };
+    for (const r of refs) {
+      const d = hamming(g.hash, r.hash);
+      if (d < best.distance) best = { ref: r.name, distance: d };
+    }
+    return { name: g.name, nearestRef: best.ref, distance: best.distance };
+  });
+}
+
+function parseArgs(argv) {
+  const o = { refsDir: '../inputs', assetsDir: '../assets', revokedArgs: [] };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--refs-dir') o.refsDir = String(argv[++i] || '');
+    else if (argv[i] === '--assets-dir') o.assetsDir = String(argv[++i] || '');
+    else if (argv[i] === '--max-distance') {
+      // Resíduo de R4 (limiar), FALSIFICADA e REVOGADA (DF5-5/DF5-6). Aceito e IGNORADO com
+      // aviso, para que um bundle compilado antes do fix round não quebre por um argumento
+      // que não afeta mais nenhuma decisão. Nunca silencioso: o aviso vai para stderr e o
+      // argumento é registrado na medida reportada.
+      o.revokedArgs.push(`--max-distance ${String(argv[++i])}`);
+    }
+  }
+  return o;
+}
+
+// ---------------------------------------------------------------------------
+// Registro do run — LIDO E ESCRITO SÓ PARA A MEDIDA (nunca para decidir).
+//
+// A verificação de proveniência que MORAVA aqui foi REMOVIDA (não afrouxada): ela agora existe
+// UMA ÚNICA VEZ, em `scripts/pod-export-tools.cjs` (`checkRunProvenance`/`assertRunProvenance`),
+// ao lado de `recordProvenance`, e é consumida pelo `pod-export-executor.cjs` — DF-SF10.19-4.
+// Com isso o contrato do ledger deixa de ter duas implementações: este script blessed (que não
+// pode importar nada fora de `veto-checks/`) só precisa saber ONDE o ledger fica para gravar a
+// medida quando ele existir. Ausência/ilegibilidade viram nota declarada, nunca exit.
+// ---------------------------------------------------------------------------
+
+/** `<runDir>.provenance.json` — IRMÃO do runDir, logo fora do alcance de escrita das tools. */
+function provenancePathFor(runDir) {
+  return path.resolve(runDir) + PROVENANCE_SUFFIX;
+}
+
+// ---------------------------------------------------------------------------
+// MEDIDA REPORTADA — nunca bloqueia (e2 de DF5-6).
+// ---------------------------------------------------------------------------
+
+/**
+ * Bloco humano-legível da medida, gravado no artefato que alimenta o checkpoint de `assembly`.
+ *
+ * O bloco DECLARA o que NÃO foi verificado (AC10 / DF-SF10.19-3). É o oposto de um selo: ele existe
+ * para que o humano que aprova o carrossel saiba exatamente qual garantia tem e qual não tem — no
+ * driver de dev, nenhuma garantia de máquina sobre a ORIGEM dos bytes.
+ */
+function renderMeasureBlock(measure) {
+  const L = [MEASURE_BEGIN, '', '## Medida de similaridade (reportada por codigo, NAO e veto)', ''];
+  L.push('Calculada por `phash-gate.cjs`, que MEDE e nunca bloqueia. Nao ha limiar e nao ha pass/fail: julgar se a');
+  L.push('peca "aderiu demais" a referencia e JULGAMENTO HUMANO, no checkpoint de `assembly`.');
+  L.push('');
+  if (measure.status === 'ok') {
+    L.push('| Peca gerada | Referencia mais proxima | Distancia perceptual (Hamming /64) |');
+    L.push('|---|---|---|');
+    for (const r of measure.rows) L.push(`| ${r.name} | ${r.nearestRef} | ${r.distance} |`);
+    L.push('');
+    L.push('Escala: 0 = layout de luminancia identico; 64 = oposto. A medida NAO separa "copia" de "peca legitima"');
+    L.push('no conteudo real (medido em SF10.8, ver docs/mecanismos/veto-nao-copia-phash.md) - use-a como indicio, nunca como prova.');
+  } else {
+    const rotulo = measure.status === 'nao-verificada' ? 'Medida NAO CALCULADA' : 'Medida AUSENTE';
+    L.push(`${rotulo} (${measure.reason}). A ausencia NAO bloqueia a etapa e NAO foi substituida por nenhum valor.`);
+  }
+  L.push('');
+  L.push('### O que este bloco NAO garante (declarado, nao omitido)');
+  L.push('');
+  L.push('- Este script NAO verifica PROVENIENCIA. Que as imagens em `assets/` tenham sido gravadas pelas tools do run,');
+  L.push('  e que a referencia em `inputs/` esteja bit-a-bit como o codigo a materializou, e asserido pelo EXECUTOR de');
+  L.push('  export (`pod-export-executor.cjs`, antes de avancar a fase) - o unico componente que confina a superficie de');
+  L.push('  tools. Em run de DESENVOLVIMENTO (`pc-run-pod`, agente com Bash/Write) essa garantia NAO EXISTE: o unico');
+  L.push('  enforcement e humano, neste checkpoint. Ver docs/mecanismos/veto-nao-copia-phash.md.');
+  L.push('- A distancia acima e um indicio de layout de luminancia. NAO e prova de nao-copia nem de autoria.');
+  L.push('', MEASURE_END);
+  return L.join('\n');
+}
+
+/** Insere/SUBSTITUI o bloco no texto do artefato (idempotente entre retentativas da etapa). */
+function upsertMeasureBlock(text, block) {
+  const b = text.indexOf(MEASURE_BEGIN);
+  const e = text.indexOf(MEASURE_END);
+  if (b >= 0 && e > b) return `${text.slice(0, b)}${block}${text.slice(e + MEASURE_END.length)}`;
+  return `${text.replace(/\s*$/, '')}\n\n${block}\n`;
+}
+
+/**
+ * Grava a medida no ledger QUANDO ele existe (no export ele existe; no dev, não). Best-effort
+ * DECLARADO: o chamador transforma qualquer falha daqui em nota no stderr — nunca em exit.
+ * LANÇA em ledger ausente/ilegível/de versão desconhecida em vez de criar ou sobrescrever um:
+ * este script não é dono do ledger e escrever um por conta própria fabricaria proveniência.
+ */
+function recordMeasure(runDir, stepId, measure) {
+  const ledgerPath = provenancePathFor(runDir);
+  const parsed = JSON.parse(fs.readFileSync(ledgerPath, 'utf8'));
+  if (!parsed || typeof parsed !== 'object' || parsed.version !== PROVENANCE_VERSION) {
+    throw new Error(`registro de proveniência com formato/versão inesperados (${ledgerPath}) — recusando escrever a medida nele`);
+  }
+  parsed.measures = (parsed.measures && typeof parsed.measures === 'object') ? parsed.measures : {};
+  parsed.measures[stepId] = measure;
+  parsed.updated_at = new Date().toISOString();
+  const tmp = `${ledgerPath}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(parsed, null, 2)}\n`, 'utf8');
+  fs.renameSync(tmp, ledgerPath);
+}
+
+/** Resolve um dir de arg LITERAL relativo ao dir do artefato, exigindo contenção no runDir. */
+function resolveWithin(runDir, artDir, rel, label) {
+  const abs = path.resolve(artDir, rel);
+  const root = path.resolve(runDir);
+  if (abs !== root && !abs.startsWith(root + path.sep)) {
+    throw new Error(`${label} "${rel}" resolve FORA do runDir (${abs}) — recusado`);
+  }
+  return abs;
+}
+
+function main() {
+  const artifact = process.argv[2];
+  if (!artifact || !fs.existsSync(artifact)) {
+    console.error(`phash-gate: artefato não encontrado: ${artifact}`);
+    process.exit(2);
+  }
+  const { refsDir, assetsDir, revokedArgs } = parseArgs(process.argv.slice(3));
+  if (revokedArgs.length > 0) {
+    console.error(`phash-gate: AVISO — argumento(s) de limiar ignorado(s) [${revokedArgs.join(', ')}]: ` +
+      'o veredito por distância perceptual foi FALSIFICADO e REVOGADO (ADR-018, Correção 1 do Adendo F5 / ' +
+      'DF5-5, DF5-6). O que bloqueia agora é PROVENIÊNCIA (sha256), sem limiar; a distância virou medida ' +
+      'reportada. Remova o argumento do wf do pod.');
+  }
+  const artDir = path.dirname(path.resolve(artifact));
+  const runDir = path.dirname(artDir); // invariante runDir/artifacts/<step>.md
+  let refsAbs; let assetsAbs;
+  try {
+    refsAbs = resolveWithin(runDir, artDir, refsDir, '--refs-dir');
+    assetsAbs = resolveWithin(runDir, artDir, assetsDir, '--assets-dir');
+  } catch (e) {
+    console.error(`phash-gate: ${e.message}`);
+    process.exit(2);
+  }
+
+  // ── MEDIDA (o único caminho que restou). NADA daqui em diante pode virar exit não-zero:
+  // insumo ausente, ledger ausente e Chrome ausente são DEGRADAÇÃO DECLARADA, não veredito
+  // (DF-SF10.19-2/e1). Quem BLOQUEIA proveniência é o executor de export, in-process.
+  // A VARREDURA dos diretórios entra no `try` (F1 do gate `pc-qa` da SF10.19): `listImages` faz IO
+  // e pode lançar (EACCES num diretório ilegível). Fora do `try`, a exceção escapava e o processo
+  // saía 1 — BLOQUEANDO, exatamente o que o comentário abaixo promete que não acontece. Comentário
+  // que o código falsifica é pior que ponto cego declarado (lição do gate da SF10.10).
+  let refFiles = []; let genFiles = [];
+  const stepId = path.basename(artifact).replace(/\.md$/i, '');
+  let measure;
+  try {
+    refFiles = listImages(refsAbs);
+    genFiles = listImages(assetsAbs);
+    if (refFiles.length === 0 || genFiles.length === 0) {
+      // Antes da SF10.19 estes dois estados eram exit 3. Eles não descrevem uma violação: descrevem
+      // um run cujo insumo de MEDIDA não está no lugar — o que é o estado NORMAL do driver de dev,
+      // que não materializa `inputs/`. Declarar é a resposta certa; bloquear travava o pod inteiro.
+      const faltas = [];
+      if (refFiles.length === 0) faltas.push(`nenhuma imagem de REFERENCIA em ${refsAbs} (no export ela e materializada por codigo a partir de inputs_dir; em run de dev ela costuma nao existir)`);
+      if (genFiles.length === 0) faltas.push(`nenhuma imagem GERADA em ${assetsAbs}`);
+      measure = { status: 'nao-verificada', reason: `insumo de medida ausente: ${faltas.join('; ')}` };
+    } else {
+      const chromeBin = probeChrome();
+      if (!chromeBin) {
+        measure = { status: 'ausente', reason: 'headless Chrome nao encontrado (defina CHROME_BIN) - a medida e opcional e nao bloqueia nada' };
+      } else {
+        const files = [
+          ...refFiles.map((abs, i) => ({ id: `r${i}`, abs, name: path.relative(runDir, abs), kind: 'ref' })),
+          ...genFiles.map((abs, i) => ({ id: `g${i}`, abs, name: path.relative(runDir, abs), kind: 'gen' })),
+        ];
+        const gray = grayscalesViaChrome(chromeBin, files);
+        const hashed = files.map((f) => ({ ...f, hash: hashFromGray(gray.get(f.id)) }));
+        measure = {
+          status: 'ok',
+          method: 'pHash DCT 64 bits sobre grayscale 32x32 (Chrome headless); distancia de Hamming',
+          blocking: false,
+          rows: measureDistances(hashed.filter((f) => f.kind === 'gen'), hashed.filter((f) => f.kind === 'ref')),
+        };
+      }
+    }
+  } catch (e) {
+    measure = { status: 'ausente', reason: `medicao falhou: ${e.message}` };
+  }
+  measure.at = new Date().toISOString();
+  // Declarado SEMPRE, em qualquer status: este script não verifica proveniência — nem no export,
+  // onde o executor a assere, nem no dev, onde ela não é verificável por ninguém (DF-SF10.19-3).
+  measure.provenance_checked_here = false;
+  measure.provenance_enforced_by = 'pod-export-executor.cjs (tools.assertRunProvenance, antes de motor.advance) — SO no driver de export';
+  if (revokedArgs.length > 0) measure.ignored_args = revokedArgs;
+
+  // Os dois destinos da medida são best-effort DECLARADO: a falha vira AVISO em stderr, nunca
+  // exit. Nada de `catch {}` cego — todo motivo é dito por extenso.
+  const notes = [];
+  try { recordMeasure(runDir, stepId, measure); } catch (e) { notes.push(`registro da medida no ledger falhou (esperado fora do export, onde nao ha ledger): ${e.message}`); }
+  try {
+    const raw = fs.readFileSync(path.resolve(artifact), 'utf8');
+    fs.writeFileSync(path.resolve(artifact), upsertMeasureBlock(raw, renderMeasureBlock(measure)), 'utf8');
+  } catch (e) { notes.push(`gravacao do bloco de medida no artefato falhou: ${e.message}`); }
+  for (const n of notes) console.error(`phash-gate: AVISO (nao-bloqueante) — ${n}`);
+
+  const detail = measure.status === 'ok'
+    ? measure.rows.map((r) => `${r.name} vs ${r.nearestRef}: ${r.distance}`).join('; ')
+    : `${measure.status} (${measure.reason})`;
+  console.log(`phash-gate: MEDIDA registrada (este script nao bloqueia) — ${genFiles.length} imagem(ns) em ` +
+    `assets/, ${refFiles.length} referencia(s) em inputs/. Similaridade: ${detail}. ` +
+    'PROVENIENCIA nao e verificada aqui: ela e asserida pelo executor de export antes de avancar a fase ' +
+    '(ADR-018, DF-SF10.19-2); em run de desenvolvimento essa garantia nao existe.');
+  process.exit(0);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  // medida reportada (o único caminho que este script tem)
+  probeChrome, hashFromGray, hamming, measureDistances, parseMarker, measurePage,
+  grayscalesViaChrome, renderMeasureBlock, upsertMeasureBlock, recordMeasure,
+  // endereço do ledger (para GRAVAR a medida; a VERIFICAÇÃO vive em pod-export-tools.cjs)
+  provenancePathFor,
+  // comuns
+  parseArgs, listImages, resolveWithin,
+  CHROME_CANDIDATES, SIDE, PROVENANCE_SUFFIX, PROVENANCE_VERSION, MEASURE_BEGIN, MEASURE_END,
+};