@daniellins/power-claude 0.16.3

package/scripts/phash-gate.test.cjs

@@ -0,0 +1,433 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * phash-gate.test.cjs — suíte do script BLESSED de MEDIDA da não-cópia.
+ * Story SF10.8 (origem) → **Story SF10.19 / ADR-018 Adendo F6-b (DF-SF10.19-1/-2/-4)**.
+ *
+ * O QUE MUDOU DE OBJETO NESTA SUÍTE (e por quê): até a SF10.19 este script tinha uma metade
+ * BLOQUEANTE (proveniência) e uma metade de medida. A metade bloqueante FOI EMBORA daqui — não
+ * porque afrouxou, mas porque ela é uma invariante de ORIGEM e o `wf-*.yaml` que declara este
+ * `command_check` é consumido por DOIS drivers, um deles não-confinado (`pc-run-pod.cjs`, agente
+ * com Bash/Write). Ela agora vive em `pod-export-tools.cjs` (`assertRunProvenance`) e é asserida
+ * pelo `pod-export-executor.cjs` antes de `motor.advance` — com suíte própria em
+ * `pod-export-executor.test.cjs` (§SF10.19), que prova o BLOQUEIO real em `run`, `resume` e
+ * tentativa guiada, inclusive com a camada 1 de INTEG-1 contornada por escrita direta com `fs`.
+ *
+ * O QUE ESTA SUÍTE PROVA AGORA:
+ *   (AC5) PROPRIEDADE, não caso pontual: NENHUM estado de insumo faz este script sair não-zero —
+ *         referência ausente, `assets/` vazio, ledger ausente/ilegível/de versão desconhecida, sha
+ *         divergente, asset intruso, entrada registrada sumida, Chrome ausente. Todos exit 0, com
+ *         `measure.status` DECLARADO e motivo. Estático + comportamental, pela rota REAL do motor;
+ *   (AC5) o único exit não-zero remanescente é 2 (uso/config: artefato inexistente, dir escapando);
+ *   (AC6) SUBSTITUTA da antiga asserção de "duas cópias do contrato do ledger não divergem": o
+ *         contrato agora tem UMA implementação (a duplicação sumiu), e o que resta a vigiar é que
+ *         o script de medida NÃO REGREDIU para bloquear + as duas pontas concordam no PATH do
+ *         ledger (que o script ainda usa para gravar a MEDIDA);
+ *   (AC5) NENHUM ramo condicional dev/export, flag, env var ou campo de modo nasceu aqui;
+ *   (INTEG-1 camada 1) as tools continuam NEGANDO escrita sob `<runDir>/inputs/` — inalterado;
+ *   (AC3b) degradação DECLARADA: Chrome ausente vira medida ausente no artefato e no ledger;
+ *   (AC10) o bloco do artefato DECLARA o que não foi verificado (proveniência), em todo status;
+ *   (DF5-6/e2) similaridade como MEDIDA REPORTADA: distância computada e gravada, sem pass/fail;
+ *   (DF5-1) materialização da referência pelo EXECUTOR + registro da proveniência.
+ *
+ * A aritmética do hash roda SEM Chrome. As provas com Chrome REAL registram SKIP HONESTO onde ele
+ * não existe. A fronteira `command_check` herdada é provada em `veto-checks.test.cjs`.
+ *
+ * Node >= 18. Exit 0/1.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+
+const rp = require('./pc-run-pod.cjs');
+const gate = require('./veto-checks/phash-gate.cjs');
+const exec = require('./pod-export-executor.cjs');
+const tools = require('./pod-export-tools.cjs');
+
+const FIX = path.join(__dirname, '__fixtures__', 'veto-checks', 'phash');
+const GATE_PATH = path.join(__dirname, 'veto-checks', 'phash-gate.cjs');
+const SIDE = gate.SIDE;
+
+let passed = 0;
+const failures = [];
+function ok(cond, label) {
+  if (cond) { passed++; console.log(`[OK   ] ${label}`); }
+  else { failures.push(label); console.error(`[FALHA] ${label}`); }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers: runDir sintético no layout REAL do motor (runDir/artifacts|assets|inputs) + o
+// registro de proveniência escrito pela MESMA função de produção (`tools.recordProvenance`).
+// ---------------------------------------------------------------------------
+
+const ARTIFACT_MD = '# visual-set\n\n## Arquivos Gerados\n- assets/cover-bg.png\n\nreferencia_copiada: nao\nconfianca: alta\n';
+
+/**
+ * @param provenance 'full' (registra refs+assets, o caminho do export) | 'none' (nenhum ledger —
+ *                   o estado NORMAL de um run de DESENVOLVIMENTO) | 'refs-only' | 'assets-only'
+ */
+function makeRunDir({ refs = [], assets = [], label = 'phash', provenance = 'full' }) {
+  const runDir = fs.mkdtempSync(path.join(os.tmpdir(), `sf10.19-${label}-`));
+  fs.mkdirSync(path.join(runDir, 'artifacts'), { recursive: true });
+  fs.mkdirSync(path.join(runDir, 'assets'), { recursive: true });
+  if (refs.length > 0) fs.mkdirSync(path.join(runDir, 'inputs'), { recursive: true });
+  fs.writeFileSync(path.join(runDir, 'artifacts', 'visuals.md'), ARTIFACT_MD, 'utf8');
+  for (const r of refs) {
+    const dst = path.join(runDir, 'inputs', r);
+    fs.copyFileSync(path.join(FIX, r), dst);
+    if (provenance === 'full' || provenance === 'refs-only') tools.recordProvenance(runDir, 'inputs', dst, { source: 'materializeInputs' });
+  }
+  for (const a of assets) {
+    const dst = path.join(runDir, 'assets', a);
+    fs.copyFileSync(path.join(FIX, a), dst);
+    if (provenance === 'full' || provenance === 'assets-only') tools.recordProvenance(runDir, 'assets', dst, { source: 'openrouter_image' });
+  }
+  return runDir;
+}
+
+/** Invoca o script pela MESMA porta do motor (evalVeto/command_check), como em produção. */
+function runGate(runDir, args = ['--refs-dir', '../inputs', '--assets-dir', '../assets']) {
+  return rp.evalVeto(
+    { type: 'command_check', command: 'phash-gate.cjs', args, timeout_ms: 120000 },
+    fs.readFileSync(path.join(runDir, 'artifacts', 'visuals.md'), 'utf8'),
+    path.join(runDir, 'artifacts', 'visuals.md'),
+    { runDir, podRoot: runDir },
+  );
+}
+
+/** Invocação DIRETA (sem o motor) — devolve o exit code real do processo. */
+function rawExit(argv) {
+  try {
+    execFileSync(process.execPath, [GATE_PATH, ...argv], { stdio: 'pipe', timeout: 120000 });
+    return 0;
+  } catch (e) { return typeof e.status === 'number' ? e.status : -1; }
+}
+
+function artifactOf(runDir) { return fs.readFileSync(path.join(runDir, 'artifacts', 'visuals.md'), 'utf8'); }
+function ledgerOf(runDir) { return JSON.parse(fs.readFileSync(gate.provenancePathFor(runDir), 'utf8')); }
+
+function grayFrom(fn) {
+  const g = new Uint8Array(SIDE * SIDE);
+  for (let y = 0; y < SIDE; y++) for (let x = 0; x < SIDE; x++) g[y * SIDE + x] = Math.max(0, Math.min(255, Math.round(fn(x, y))));
+  return g;
+}
+
+// ===========================================================================
+// 1. Contrato do ledger: a DUPLICAÇÃO acabou (DF-SF10.19-4). O que resta a vigiar é o PATH.
+// ===========================================================================
+console.log('--- 1. contrato do ledger: uma única implementação (a duplicação foi removida) ---');
+{
+  const rd = fs.mkdtempSync(path.join(os.tmpdir(), 'sf10.19-contrato-'));
+  ok(tools.provenancePathFor(rd) === gate.provenancePathFor(rd),
+    'tools e blessed derivam o MESMO path de registro (o script ainda GRAVA a medida nele)');
+  ok(gate.provenancePathFor(rd) === path.resolve(rd) + '.provenance.json',
+    'o registro é IRMÃO do runDir (fora da árvore gravável pelas tools por construção)');
+  let threwSibling = false;
+  try { tools.confinedResolve(rd, `../${path.basename(rd)}.provenance.json`); } catch { threwSibling = true; }
+  ok(threwSibling, 'nenhuma tool alcança o registro: o path do irmão é traversal para fora do runDir → RECUSADO');
+  ok(tools.RUN_INPUTS_DIRNAME === 'inputs' && exec.RUN_INPUTS_DIRNAME === tools.RUN_INPUTS_DIRNAME,
+    'RUN_INPUTS_DIRNAME tem fonte ÚNICA (tools) e o executor a reexporta — sem literal duplicado');
+
+  // AC2/AC6 — a VERIFICAÇÃO existe uma vez só, e não é mais aqui.
+  ok(typeof gate.checkProvenance === 'undefined' && typeof gate.loadProvenance === 'undefined',
+    'AC2: o blessed NÃO expõe mais verificação de proveniência (checkProvenance/loadProvenance removidos)');
+  ok(typeof tools.checkRunProvenance === 'function' && typeof tools.assertRunProvenance === 'function',
+    'AC2: a checagem canônica vive em pod-export-tools.cjs, ao lado de recordProvenance');
+  const gateSrc = fs.readFileSync(GATE_PATH, 'utf8');
+  ok(!/\bsha256\s*\(|createHash/.test(gateSrc),
+    'AC2: o blessed não recalcula sha256 de nada — ele não tem mais o que decidir com isso');
+
+  const f = path.join(rd, 'x.bin');
+  fs.writeFileSync(f, Buffer.from('conteudo'));
+  const rec = tools.recordProvenance(rd, 'assets', f);
+  ok(rec.sha256 === crypto.createHash('sha256').update(fs.readFileSync(f)).digest('hex'),
+    'sha256 do registro = sha256 do arquivo em disco (a gravação do ledger não mudou)');
+  fs.writeFileSync(gate.provenancePathFor(rd), '{ isso não é json', 'utf8');
+  let threwCorrupt = false;
+  try { tools.recordProvenance(rd, 'assets', f); } catch { threwCorrupt = true; }
+  ok(threwCorrupt, 'registro corrompido: recordProvenance RECUSA gravar por cima (fail-loud, não reseta proveniência)');
+}
+
+// ===========================================================================
+// 2. AC5 — PROPRIEDADE: nenhum estado de insumo produz exit não-zero.
+//    Isto SUBSTITUI (não apaga) a antiga asserção anti-divergência das duas cópias do contrato:
+//    o risco que ela protegia deixou de existir com a implementação única; o risco que EXISTE
+//    agora é este script REGREDIR para bloquear e travar o driver de dev de novo.
+// ===========================================================================
+console.log('--- 2. AC5 (PROPRIEDADE): nenhum estado de insumo bloqueia ---');
+{
+  // (a) ESTÁTICO: não há caminho de bloqueio no fonte.
+  const src = fs.readFileSync(GATE_PATH, 'utf8');
+  const exits = [...src.matchAll(/process\.exit\((\d+)\)/g)].map((m) => m[1]);
+  ok(exits.every((c) => c === '0' || c === '2') && exits.includes('0') && exits.includes('2'),
+    `AC5 (estático): os únicos process.exit do script são 0 e 2 (encontrados: ${[...new Set(exits)].join(', ')})`);
+  ok(!/process\.exit\(1\)|process\.exit\(3\)/.test(src),
+    'AC5 (estático): exit 1 (proveniência violada) e exit 3 (fail-loud de insumo) não existem mais');
+
+  // (b) ESTÁTICO: nenhum ramo condicional dev/export, flag, env ou campo de modo (Escopo OUT).
+  const envs = [...new Set([...src.matchAll(/process\.env\.([A-Z_0-9]+)/g)].map((m) => m[1]))];
+  ok(envs.join(',') === 'CHROME_BIN', `Escopo OUT: a única env var lida continua sendo CHROME_BIN (${envs.join(', ') || 'nenhuma'})`);
+  ok(!/--(dev|mode|export|skip|allow)[-\w]*/.test(src), 'Escopo OUT: nenhum arg de CLI de modo/skip nasceu no script');
+  ok(!/\b(isDev|devMode|inExport|driverIsDev|IS_DEV)\b/.test(src), 'Escopo OUT: nenhum identificador de "modo dev vs export" no script');
+  const parsed = gate.parseArgs(['--refs-dir', 'a', '--assets-dir', 'b']);
+  ok(Object.keys(parsed).sort().join(',') === 'assetsDir,refsDir,revokedArgs',
+    `Escopo OUT: parseArgs não ganhou opção nova (${Object.keys(parsed).sort().join(', ')}) — args de CLI INALTERADOS`);
+
+  // (c) COMPORTAMENTAL: a matriz de estados de insumo, TODA pela rota real do motor.
+  const estados = [
+    ['tudo íntegro (o caminho do export)', () => makeRunDir({ refs: ['ref.png'], assets: ['distinct.png'], label: 'p-ok' })],
+    ['referência NÃO materializada (o estado NORMAL do driver de dev)', () => makeRunDir({ refs: [], assets: ['distinct.png'], label: 'p-norefs' })],
+    ['assets/ vazio (etapa ainda não gerou imagem)', () => makeRunDir({ refs: ['ref.png'], assets: [], label: 'p-noassets' })],
+    ['assets/ e inputs/ vazios (run recém-criado)', () => makeRunDir({ refs: [], assets: [], label: 'p-vazio' })],
+    ['ledger AUSENTE (dev: ninguém escreve ledger)', () => makeRunDir({ refs: ['ref.png'], assets: ['distinct.png'], label: 'p-noledger', provenance: 'none' })],
+    ['ledger ILEGÍVEL', () => { const rd = makeRunDir({ refs: ['ref.png'], assets: ['distinct.png'], label: 'p-badledger' }); fs.writeFileSync(gate.provenancePathFor(rd), '{ quebrado', 'utf8'); return rd; }],
+    ['ledger de VERSÃO DESCONHECIDA', () => { const rd = makeRunDir({ refs: ['ref.png'], assets: ['distinct.png'], label: 'p-verledger' }); fs.writeFileSync(gate.provenancePathFor(rd), JSON.stringify({ version: 99, inputs: {}, assets: {} }), 'utf8'); return rd; }],
+    ['sha DIVERGENTE em inputs/ (referência trocada)', () => { const rd = makeRunDir({ refs: ['ref.png'], assets: ['distinct.png'], label: 'p-div' }); fs.copyFileSync(path.join(FIX, 'copy.png'), path.join(rd, 'inputs', 'ref.png')); return rd; }],
+    ['imagem INTRUSA em assets/ (fora do ledger)', () => { const rd = makeRunDir({ refs: ['ref.png'], assets: ['distinct.png'], label: 'p-intrusa' }); fs.copyFileSync(path.join(FIX, 'copy.png'), path.join(rd, 'assets', 'intrusa.png')); return rd; }],
+    ['entrada registrada que SUMIU do disco', () => { const rd = makeRunDir({ refs: ['ref.png'], assets: ['distinct.png'], label: 'p-sumiu' }); fs.rmSync(path.join(rd, 'assets', 'distinct.png')); return rd; }],
+    ['ledger só com refs (assets sem registro)', () => makeRunDir({ refs: ['ref.png'], assets: ['distinct.png'], label: 'p-refsonly', provenance: 'refs-only' })],
+  ];
+  const bloquearam = [];
+  for (const [nome, mk] of estados) {
+    const rd = mk();
+    const r = runGate(rd);
+    if (r.ok !== true) bloquearam.push(`${nome} → ${String(r.reason).slice(0, 120)}`);
+    // Em TODO estado o artefato recebe o bloco de medida, e ele DECLARA o que não foi verificado.
+    const art = artifactOf(rd);
+    if (!/pc:medida-similaridade:inicio/.test(art) || !/NAO verifica PROVENIENCIA/.test(art)) {
+      bloquearam.push(`${nome} → bloco de medida ausente ou sem a declaração do que não foi verificado`);
+    }
+  }
+  ok(bloquearam.length === 0,
+    `AC5 (comportamental): NENHUM dos ${estados.length} estados de insumo bloqueia, e todos declaram a degradação${bloquearam.length ? ' — VIOLAÇÕES: ' + bloquearam.join(' | ') : ''}`);
+
+  // (c2) F1 do gate `pc-qa` da SF10.19: diretório de insumo ILEGÍVEL (EACCES). `listImages` faz IO
+  // e estava FORA do try — a exceção escapava e o processo saía 1, BLOQUEANDO, contra a promessa
+  // escrita duas linhas acima dela. Regressão vigiada aqui, no mesmo lugar da propriedade.
+  for (const dir of ['assets', 'inputs']) {
+    const rd = makeRunDir({ refs: ['ref.png'], assets: ['distinct.png'], label: `eacces-${dir}` });
+    const alvo = path.join(rd, dir);
+    fs.chmodSync(alvo, 0o000);
+    let legivelMesmoAssim = true;
+    try { fs.readdirSync(alvo); } catch { legivelMesmoAssim = false; }
+    if (legivelMesmoAssim) { // root ignora o modo: SKIP HONESTO em vez de asserção vazia
+      fs.chmodSync(alvo, 0o755);
+      console.log(`[SKIP ] EACCES em ${dir}/ não é reproduzível neste ambiente (usuário ignora o modo do diretório)`);
+      continue;
+    }
+    const r = runGate(rd);
+    fs.chmodSync(alvo, 0o755);
+    const art = artifactOf(rd);
+    ok(r.ok === true, `AC5/F1: ${dir}/ ILEGÍVEL (EACCES) NÃO bloqueia — antes do fix o script saía 1 aqui`);
+    ok(/Medida AUSENTE/.test(art) && /EACCES/.test(art),
+      `AC5/F1: a falha de leitura de ${dir}/ vira DEGRADAÇÃO DECLARADA com o errno no artefato (nunca silêncio, nunca veto)`);
+  }
+
+  // (d) O estado que HOJE trava o pod no uso interativo, nomeado: é o motivo desta story.
+  const rdDev = makeRunDir({ refs: [], assets: [], label: 'p-dev', provenance: 'none' });
+  const rDev = runGate(rdDev);
+  ok(rDev.ok === true,
+    'AC5 (o defeito que a story conserta): run de DEV sem inputs/ e sem ledger — o mesmo estado que dava "exit 3: nenhuma imagem de REFERÊNCIA" — PASSA');
+  ok(/Medida NAO CALCULADA/.test(artifactOf(rdDev)) && /REFERENCIA/.test(artifactOf(rdDev)),
+    'AC5: e o artefato DIZ por que não houve medida (degradação declarada, nunca omissão)');
+}
+
+// ===========================================================================
+// 3. AC5 — o único exit não-zero que sobra: 2 (uso/config inválida, erro de WIRING)
+// ===========================================================================
+console.log('--- 3. exit 2 (uso/config) é o único não-zero remanescente ---');
+{
+  ok(rawExit([path.join(os.tmpdir(), 'nao-existe-artefato-xyz.md')]) === 2, 'artefato inexistente → exit 2 (uso inválido)');
+  ok(rawExit([]) === 2, 'sem argumento de artefato → exit 2');
+  const rd = makeRunDir({ refs: ['ref.png'], assets: ['distinct.png'], label: 'e-badarg' });
+  const art = path.join(rd, 'artifacts', 'visuals.md');
+  ok(rawExit([art, '--refs-dir', '../../../etc']) === 2, '--refs-dir que escapa do runDir → exit 2, nunca lido');
+  ok(rawExit([art, '--assets-dir', '../../..']) === 2, '--assets-dir que escapa do runDir → exit 2');
+  ok(runGate(rd, ['--refs-dir', '../../../etc', '--assets-dir', '../assets']).ok === false,
+    'pela rota do motor, o arg inválido também é RECUSADO (erro de wiring é idêntico nos dois drivers)');
+  ok(rawExit([art]) === 0, 'com wiring válido, exit 0 (defaults ../inputs e ../assets)');
+}
+
+// ===========================================================================
+// 4. INTEG-1 — CAMADA 1 (denylist de escrita nas tools) segue INTACTA.
+//    A CAMADA 2 (registro sha256) mudou de HOSPEDEIRO, não de força: ela é provada, com a camada 1
+//    CONTORNADA por escrita direta com `fs`, em `pod-export-executor.test.cjs` §SF10.19 — onde o
+//    run é HALTADO. Aqui provamos que o script de medida, sozinho, não é mais o guardião disso.
+// ===========================================================================
+console.log('--- 4. INTEG-1: camada 1 intacta (camada 2 provada no executor) ---');
+const PNG_1X1 = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M8AAAMBAQDJ/pLvAAAAAElFTkSuQmCC';
+const imageTransport = async () => ({ choices: [{ message: { images: [{ image_url: { url: PNG_1X1 } }] } }] });
+
+(async () => {
+  const rd = makeRunDir({ refs: ['ref.png'], assets: [], label: 'integ-c1' });
+  const antes = tools.sha256File(path.join(rd, 'inputs', 'ref.png'));
+  const r = await tools.openrouterImage('desenhe', 'inputs/ref.png', { runDir: rd, model: 'm', imageTransport });
+  const depois = tools.sha256File(path.join(rd, 'inputs', 'ref.png'));
+  ok(r.ok === false && /PROIBIDA/.test(r.error) && /inputs/.test(r.error),
+    'CAMADA 1: openrouter_image(out_path:"inputs/<ref>") é RECUSADO pela denylist (cenário exato do QA, INTEG-1)');
+  ok(antes === depois, 'CAMADA 1: a referência em disco fica INTACTA (a tool nem chegou a escrever)');
+  const rUp = await tools.openrouterImage('desenhe', 'INPUTS/ref.png', { runDir: rd, model: 'm', imageTransport });
+  ok(rUp.ok === false && /PROIBIDA/.test(rUp.error),
+    'CAMADA 1: variação de CAIXA ("INPUTS/") também é recusada (filesystem case-insensitive não abre buraco)');
+  const rDot = await tools.openrouterImage('desenhe', 'assets/../inputs/ref.png', { runDir: rd, model: 'm', imageTransport });
+  ok(rDot.ok === false && /PROIBIDA/.test(rDot.error), 'CAMADA 1: caminho indireto ("assets/../inputs/") também é recusado');
+  let threwWrite = false;
+  try { tools.writeFile('inputs/ref.png', 'texto', { runDir: rd }); } catch (e) { threwWrite = /PROIBIDA/.test(e.message); }
+  ok(threwWrite, 'CAMADA 1: write_file sob inputs/ também é recusado (a denylist vale para TODA tool de escrita)');
+  const rOk = await tools.openrouterImage('desenhe', 'assets/cover-bg.png', { runDir: rd, model: 'm', imageTransport });
+  ok(rOk.ok === true && fs.existsSync(path.join(rd, 'assets', 'cover-bg.png')),
+    'CAMADA 1 não é bloqueio geral: gravar em assets/ continua funcionando (mudança aditiva)');
+  ok(ledgerOf(rd).assets['assets/cover-bg.png'].sha256 === tools.sha256File(path.join(rd, 'assets', 'cover-bg.png')),
+    'toda gravação por openrouter_image é REGISTRADA no ledger com o sha256 do que ficou em disco');
+
+  // A CAMADA 2 continua detectando a mesma classe — só que no EXECUTOR, e agora com HALT.
+  const rd2 = makeRunDir({ refs: ['ref.png'], assets: ['distinct.png'], label: 'integ-c2' });
+  ok(tools.checkRunProvenance({ runDir: rd2 }).ok === true, 'CAMADA 2 (baseline): com a referência íntegra, a checagem canônica PASSA');
+  fs.copyFileSync(path.join(FIX, 'copy.png'), path.join(rd2, 'inputs', 'ref.png')); // denylist contornada com fs
+  const v2 = tools.checkRunProvenance({ runDir: rd2 });
+  ok(v2.ok === false && /DIVERGE/.test(v2.violations.join(' ')) && /ref\.png/.test(v2.violations.join(' ')),
+    'CAMADA 2: referência SUBSTITUÍDA por fora das tools → detectada por divergência de sha256 (fecha a CLASSE)');
+  ok(runGate(rd2).ok === true,
+    'e o script de MEDIDA não é mais quem recusa isso (quem HALTA é o executor — pod-export-executor.test.cjs §SF10.19)');
+
+  // =========================================================================
+  // 5. MEDIDA REPORTADA (DF5-6/e2) e DEGRADAÇÃO DECLARADA (AC3b/AC10)
+  // =========================================================================
+  console.log('--- 5. medida reportada e degradação declarada ---');
+  {
+    const rd4 = makeRunDir({ refs: ['ref.png'], assets: ['distinct.png'], label: 'degrada' });
+    const saved = process.env.CHROME_BIN;
+    process.env.CHROME_BIN = '/nao/existe/chrome-xyz';
+    const r4 = runGate(rd4);
+    if (saved === undefined) delete process.env.CHROME_BIN; else process.env.CHROME_BIN = saved;
+    ok(r4.ok === true, 'AC3b: Chrome ausente NÃO bloqueia a etapa');
+    const art = artifactOf(rd4);
+    ok(/Medida AUSENTE/.test(art) && /Chrome/.test(art),
+      'AC3b: a medida é declarada AUSENTE no artefato (nunca omitida, nunca substituída por um valor)');
+    const m = ledgerOf(rd4).measures.visuals;
+    ok(m && m.status === 'ausente' && typeof m.reason === 'string',
+      'AC3b: a ausência fica registrada no ledger com o motivo (degradação DECLARADA, não silenciosa)');
+    ok(m.provenance_checked_here === false && /pod-export-executor/.test(String(m.provenance_enforced_by)),
+      'AC10: o registro da medida DIZ que a proveniência não foi verificada aqui e nomeia quem a assere');
+    ok(/NAO verifica PROVENIENCIA/.test(art) && /pc-run-pod/.test(art) && /NAO EXISTE/.test(art),
+      'AC10: o bloco do artefato declara, por extenso, que no driver de dev a garantia de origem NÃO existe');
+  }
+  {
+    const rd5 = makeRunDir({ refs: ['ref.png'], assets: ['distinct.png'], label: 'revogado' });
+    const r5 = runGate(rd5, ['--refs-dir', '../inputs', '--assets-dir', '../assets', '--max-distance', '10']);
+    ok(r5.ok === true, '--max-distance (resíduo de R4 revogada) NÃO altera o veredito — é ignorado, não é gate');
+    const m = ledgerOf(rd5).measures.visuals;
+    ok(Array.isArray(m.ignored_args) && /max-distance/.test(m.ignored_args.join(' ')),
+      'o argumento revogado fica REGISTRADO como ignorado (nunca silencioso)');
+  }
+  if (gate.probeChrome()) {
+    const rd6 = makeRunDir({ refs: ['ref.png'], assets: ['copy.png', 'distinct.png'], label: 'medida' });
+    const r6 = runGate(rd6);
+    ok(r6.ok === true,
+      'peça quase-idêntica à referência (dist. baixa) PASSA: similaridade NÃO é veredito [Chrome real]');
+    const m = ledgerOf(rd6).measures.visuals;
+    ok(m.status === 'ok' && m.blocking === false && m.rows.length === 2 && m.rows.every((x) => Number.isInteger(x.distance)),
+      'a distância é computada por peça e gravada no ledger como medida NÃO-bloqueante [Chrome real]');
+    const byName = Object.fromEntries(m.rows.map((x) => [path.basename(x.name), x.distance]));
+    console.log(`[MEDIDA REPORTADA] copy.png=${byName['copy.png']}/64 · distinct.png=${byName['distinct.png']}/64 ` +
+      '(sem pass/fail: nenhum limiar separa as classes no conteúdo real — DF5-5)');
+    ok(byName['copy.png'] < byName['distinct.png'],
+      'a medida ORDENA como se espera (cópia mais perto que peça distinta) sem virar veredito [Chrome real]');
+    const art = artifactOf(rd6);
+    ok(/Medida de similaridade/.test(art) && /NAO e veto/.test(art) && /copy\.png/.test(art),
+      'o artefato que alimenta o checkpoint humano de assembly recebe a medida, rotulada como não-veto [Chrome real]');
+    const antesArt = artifactOf(rd6);
+    runGate(rd6);
+    const depoisArt = artifactOf(rd6);
+    ok((depoisArt.match(/pc:medida-similaridade:inicio/g) || []).length === 1 && depoisArt.length === antesArt.length,
+      'o bloco de medida é IDEMPOTENTE entre retentativas (substituído, nunca duplicado) [Chrome real]');
+    // AC10 — a MEDIDA passa a funcionar TAMBÉM no dev (DF5-6/e2 AMPLIADA): sem ledger nenhum.
+    const rd7 = makeRunDir({ refs: ['ref.png'], assets: ['distinct.png'], label: 'medida-dev', provenance: 'none' });
+    const r7 = runGate(rd7);
+    const art7 = artifactOf(rd7);
+    ok(r7.ok === true && /Distancia perceptual/.test(art7),
+      'DF5-6/e2 AMPLIADA: em run SEM ledger (dev) a medida é calculada e gravada no artefato [Chrome real]');
+    ok(!fs.existsSync(gate.provenancePathFor(rd7)),
+      'e o script NÃO cria um ledger por conta própria (fabricar proveniência seria pior que não ter)');
+  } else {
+    console.log('[SKIP ] medida com Chrome real ausente neste ambiente (a degradação declarada já foi provada acima)');
+  }
+
+  // =========================================================================
+  // 6. Aritmética da medida (JS puro, sem Chrome)
+  // =========================================================================
+  console.log('--- 6. aritmética do hash perceptual (medida, não veredito) ---');
+  const gA = grayFrom((x, y) => (x < 16 ? 40 : 200) + ((y * 3) % 17) + (x * y) % 11);
+  const gB = grayFrom((x, y) => 255 - ((x < 16 ? 40 : 200) + ((y * 3) % 17)));
+  const hA = gate.hashFromGray(gA);
+  ok(/^[0-9a-f]{16}$/.test(hA), 'hashFromGray devolve hex de 64 bits');
+  ok(hA === gate.hashFromGray(gA), 'hashFromGray é determinístico (mesma entrada, mesmo hash)');
+  ok(gate.hamming(hA, hA) === 0, 'Hamming de hashes iguais = 0');
+  ok(gate.hamming('0000000000000000', 'ffffffffffffffff') === 64, 'Hamming de hashes opostos = 64');
+  ok(gate.hamming(hA, gate.hashFromGray(gB)) > 0, 'imagens de estrutura diferente têm hashes diferentes');
+  let threwShort = false;
+  try { gate.hashFromGray(new Uint8Array(10)); } catch { threwShort = true; }
+  ok(threwShort, 'hashFromGray recusa grayscale de tamanho inesperado (nunca hash silencioso)');
+  const rows = gate.measureDistances(
+    [{ name: 'assets/a.png', hash: '0000000000000003' }, { name: 'assets/b.png', hash: 'ffffffff0000ffff' }],
+    [{ name: 'inputs/ref.png', hash: '0000000000000000' }],
+  );
+  ok(rows.length === 2 && rows[0].distance === 2 && rows[1].distance === 48,
+    'measureDistances devolve a MENOR distância por peça (por-imagem), sem campo de veredito');
+  ok(rows.every((r) => !('copy' in r) && !('ok' in r)), 'nenhuma linha da medida carrega pass/fail — o veredito saiu do caminho');
+  ok(typeof gate.decide === 'undefined', 'a função de veredito por limiar (decide) foi REMOVIDA do módulo (R4 revogada)');
+  ok(gate.parseArgs(['--max-distance', '10']).revokedArgs.length === 1 && gate.parseArgs([]).maxDistance === undefined,
+    'parseArgs não expõe limiar: --max-distance vira argumento REVOGADO registrado');
+  ok(gate.parseMarker(`<html data-phash-gate="OK;g0:${Buffer.from(gA).toString('hex')}">`).ok === true, 'parseMarker lê o grayscale do marcador OK');
+  ok(gate.parseMarker('<html>').ok === false, 'parseMarker: marcador AUSENTE → falha (nunca green-fake)');
+  let threwOut = false;
+  try { gate.resolveWithin('/run', '/run/artifacts', '../../etc', '--refs-dir'); } catch { threwOut = true; }
+  ok(threwOut, 'resolveWithin RECUSA dir que escapa do runDir (defesa em profundidade sobre o arg literal)');
+
+  // =========================================================================
+  // 7. Materialização + registro da referência pelo EXECUTOR (DF5-1 + DF5-6) — INALTERADO
+  // =========================================================================
+  console.log('--- 7. materialização e registro da referência (executor) ---');
+  const fakeBundle = ({ vetoScripts }) => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'sf10.19-bundle-'));
+    fs.mkdirSync(path.join(root, 'phases', 'visuals'), { recursive: true });
+    fs.writeFileSync(path.join(root, 'phases', 'visuals', 'meta.json'), JSON.stringify({ agent: 'carousel-visual', veto_scripts: vetoScripts }, null, 2));
+    return root;
+  };
+  const bundleRoot = fakeBundle({ vetoScripts: ['phash-gate.cjs'] });
+  ok(exec.phasesRequiringRefs(bundleRoot).join(',') === 'visuals',
+    'phasesRequiringRefs lê o veto do meta.json do bundle (escrito pelo compilador, não por texto de agente)');
+  const inputsDir = fs.mkdtempSync(path.join(os.tmpdir(), 'sf10.19-inputs-'));
+  fs.copyFileSync(path.join(FIX, 'ref.png'), path.join(inputsDir, 'ref-pinterest.png'));
+  fs.mkdirSync(path.join(inputsDir, 'sub'), { recursive: true }); // diretório é ignorado (só arquivos regulares)
+  const runDir = fs.mkdtempSync(path.join(os.tmpdir(), 'sf10.19-run-'));
+  const rMat = exec.materializeInputs({ bundleRoot, inputsDir, runDir });
+  ok(fs.existsSync(path.join(runDir, 'inputs', 'ref-pinterest.png')) && rMat.copied.length === 1,
+    'materializeInputs COPIA a referência para <runDir>/inputs/ por CÓDIGO (não depende de read_image do modelo)');
+  ok(ledgerOf(runDir).inputs['inputs/ref-pinterest.png'].sha256 === tools.sha256File(path.join(runDir, 'inputs', 'ref-pinterest.png')),
+    'materializeInputs REGISTRA o sha256 da referência materializada (camada 2 nasce no arranque do run)');
+  exec.materializeInputs({ bundleRoot, inputsDir, runDir });
+  ok(tools.checkRunProvenance({ runDir }).ok,
+    'materializeInputs é idempotente (run e resume) e mantém a proveniência íntegra');
+  let msg = '';
+  try { exec.materializeInputs({ bundleRoot, inputsDir: null, runDir: fs.mkdtempSync(path.join(os.tmpdir(), 'sf10.19-run2-')) }); }
+  catch (e) { msg = e.message; }
+  ok(/phash-gate\.cjs/.test(msg) && /inputs_dir/.test(msg),
+    'fase que declara o veto SEM inputs_dir → ABORTA fail-loud antes de gastar API');
+  const plainBundle = fakeBundle({ vetoScripts: ['lexical-check.cjs'] });
+  let threw = false;
+  try { exec.materializeInputs({ bundleRoot: plainBundle, inputsDir: null, runDir: fs.mkdtempSync(path.join(os.tmpdir(), 'sf10.19-run3-')) }); }
+  catch { threw = true; }
+  ok(!threw, 'pod SEM o veto de não-cópia não passa a exigir inputs_dir (mudança ADITIVA, sem regressão)');
+
+  if (failures.length > 0) {
+    console.error(`\nSuíte phash-gate FALHOU: ${failures.length} de ${passed + failures.length}.`);
+    process.exit(1);
+  }
+  console.log(`\n${passed} asserções verdes. phash-gate.cjs é MEDIDA-ONLY (nenhum estado de insumo bloqueia); ` +
+    'a PROVENIÊNCIA bloqueia no executor de export (pod-export-executor.test.cjs §SF10.19).');
+  process.exit(0);
+})().catch((e) => { console.error('[FALHA] exceção não tratada na suíte:', e); process.exit(1); });