Saída estruturada & ferramentas

Um modelo de linguagem devolve texto. Texto pode estar errado, truncado, embrulhado em prosa ou em cercas de markdown. Saída estruturada é a disciplina de transformar esse texto frouxo num objeto tipado e validado antes que qualquer outra parte do sistema confie nele. No harness do Alembic isso acontece numa fronteira (boundary) específica, com Zod, e — esta é a parte honesta — com um limite claro do que ele faz e do que não faz.

Por que isto importa para o exemplo recorrente

No caminho pedido → tier → adapter → gates, os gates (Proof, verifier) confiam que um Result.ok === true carrega um objeto bem-formado. Essa confiança só é legítima porque a fronteira do adapter já provou a forma. Se a validação fosse frouxa, o erro vazaria para frente e estouraria num lugar distante e difícil de depurar — exatamente o modo de falha "malformed JSON" que o HARNESS-MAP lista como produção-realista (princípio #22).

O único "remendo" que existe — e por que não é reparo

Há um lugar no repo que tenta recuperar JSON de uma resposta embrulhada: looseJsonParse, no funil de destilação. Mas leia o que ele realmente faz:

// Tenta um parse direto; depois a primeira fatia balanceada {...}.
export const looseJsonParse = (text: string): unknown => {
  const tryParse = (s: string): unknown | undefined => {
    try { return JSON.parse(s) as unknown; }
    catch { return undefined; }
  };
  const direct = tryParse(text.trim());
  if (direct !== undefined) return direct;
  const start = text.indexOf('{');
  const end = text.lastIndexOf('}');
  if (start >= 0 && end > start) return tryParse(text.slice(start, end + 1));
  return undefined;  // nada recuperável → o sinal é DESCARTADO acima
};

É exatamente fatia + descarta: tenta o texto inteiro; se falhar, recorta do primeiro { ao último } e tenta de novo; se ainda falhar, devolve undefined. E quem chama (signalFromResult) trata undefined descartando o sinal — não re-perguntando, não consertando vírgula, não fechando chave.

/**
 * A superfície de ferramentas MCP é estritamente READ-ONLY.
 * Não há, de propósito, nenhuma tool `start`/`fanout` aqui: um cliente MCP
 * pode INSPECIONAR um run (status, swimlanes, o ledger de parked) mas nunca
 * pode causar execução autônoma por esta superfície. Essa assimetria É a
 * propriedade de segurança — o transporte menos confiável (um host MCP
 * arbitrário) recebe a MENOR autoridade. Cada handler valida sua entrada
 * com Zod e devolve um ToolResult; nenhum lança.
 */

As três ferramentas expostas são harness_status, harness_events e harness_lane — todas leitura pura. Cada uma valida seus argumentos via Zod (invokeTool faz safeParse antes de despachar), então uma chamada MCP malformada vira um erro tipado, não uma exceção.

A assimetria de capacidade, em uma imagem

export const runIdFor = (spec: unknown): string =>
  `run-${shortHash(spec)}`;

await writeFile(tmp, renderReport(report));
await rename(tmp, final); // atômico = commit

Junte as duas peças e você tem replay seguro: re-rodar um run idêntico reusa o diretório endereçado por conteúdo + o journal append-only + o cache de resultado. A segurança de repetição vem da arquitetura (conteúdo-endereçado + rename atômico + journal), não de tokens de idempotência por ferramenta.

// 1) A resposta crua do gateway é dado externo -> safeParse (nunca lança).
const parsed = openAiChatResponseSchema.safeParse(response.value.body);
if (!parsed.success) {
  return makeFailure(
    { ...ctx, durationMs, raw: response.value.body },
    makeError(ErrorCode.PARSE_ERROR, `malformed response: ${parsed.error.message}`),
  );
}

const text = extractText(parsed.data);
if (text === undefined) {       // 200, mas sem conteúdo de assistant
  return makeFailure(
    { ...ctx, durationMs, raw: response.value.body },
    makeError(ErrorCode.PARSE_ERROR, 'response had no assistant content'),
  );
}

// 2) O sucesso é NOSSO objeto -> parse (LANÇA se malformado = bug do Alembic).
return modelRunSuccessSchema.parse({
  ok: true,
  adapterId: config.adapterId,
  durationMs: Math.max(0, durationMs),
  modelId: input.modelId,
  text,
  raw: response.value.body,
  ...(usage ? { usage } : {}),
  ...(costUsd === undefined ? {} : { costUsd }),
}) satisfies ModelRunResult;

Comparativo A · Sucesso silencioso vs falha tipada

const data = JSON.parse(resp.body);
// se body for lixo -> THROW lá longe
// se faltar campo -> undefined viaja
useIt(data.text); // estoura aqui, sem contexto

const parsed = schema.safeParse(resp.body);
if (!parsed.success)
  return makeFailure(
    { raw: resp.body }, // corpo cru anexado
    makeError(PARSE_ERROR, parsed.error.message));

Comparativo B · Reparar (livro-texto) vs descartar (Alembic)