Web profunda — webSearch / webExtract, ports sobre fetch

A web é o mundo lá fora: caótica, não confiável, às vezes fora do ar. A sabedoria deste subsistema é tratar tudo que vem de fora como suspeito — e deixar o contrato (o que é uma "linha de busca válida") na mão de uma camada só, o kernel.

As duas fronteiras do subsistema: o backend fino mapeia de forma defensiva; o kernel valida com Zod e é o dono do contrato.

A fonte se constrói em torno de dois seams — um registry de providers e uma passada opcional de compressão por LLM. Ambos viram ports injetados; este módulo importa nenhum SDK e nenhum backend concreto:

export interface WebBackend {
  /* ok([]) p/ nenhum hit · err p/ falha de provider/rede */
  search(query: WebSearchQuery): Promise<Result<readonly WebSearchResult[], Error>>;
  extract(url: string): Promise<Result<WebExtractResult, Error>>;
}

export type Compressor = (
  text: string, instruction: string,
) => Promise<Result<string, Error>>;   // opcional; ausente ⇒ conteúdo cru

Uma falha de rede é err; uma busca vazia é ok([]) — a diferença é preservada no tipo, exatamente como o data.web vazio da fonte. O Compressor espelha o seam ReviewProposer do loop de aprendizado: "uma chamada de modelo em produção, um fake nos testes".

O fluxo tem duas fronteiras. O backend fetch mapeia o JSON não confiável de forma defensiva (formas desconhecidas → strings vazias); depois o kernel re-valida cada linha com Zod, falhando a chamada inteira no primeiro erro:

const parsedQuery = webSearchQuerySchema.safeParse(query);
if (!parsedQuery.success)
  return err(new Error(`Invalid web search query: …`));

const found = await deps.backend.search(clampQuery(parsedQuery.data)); // clamp [1,100]
if (!found.ok) return found;

const validated: WebSearchResult[] = [];
for (const raw of found.value) {
  const parsed = webSearchResultSchema.safeParse(raw); // linha não confiável do backend
  if (!parsed.success)
    return err(new Error(`Invalid web search result: …`)); // 1 ruim ⇒ falha tudo
  validated.push(parsed.data);
}
return ok(validated);

export const webSearchResultSchema = z.object({
  title: z.string(),                       // pode ser vazio
  url: z.string().url('result url must be a valid URL'), // ⇐ o portão
  snippet: z.string(),                     // o `description` da fonte, renomeado
});

maxResults é "clampado" para [1, 100] antes de o backend ver — o min(max(limit, 1), 100) da fonte:

const clampQuery = (query: WebSearchQuery): WebSearchQuery => {
  if (query.maxResults === undefined) return query; // ausente ⇒ passa adiante
  const clamped = Math.min(Math.max(query.maxResults, 1), 100);
  return { ...query, maxResults: clamped };
};

O teste "clamps maxResults into [1, 100]" manda 9999 e 1 e afirma que o backend vê exatamente [100, 1].

Três decisões que o tipo Result preserva: vazio ≠ erro, o clamp [1,100], e o piso de compressão.

Um conjunto de resultados vazio é ok([]), não um erro — "nenhum hit" é uma busca bem-sucedida, distinta de "o provider caiu" (err):

Para extrações, um Compressor injetado pode encolher páginas grandes para economizar tokens. Ele é pulado abaixo de um piso de tamanho (comprimir conteúdo pequeno desperdiça uma chamada de modelo) e é ausente por padrão:

const minLength = deps.compressMinLength ?? DEFAULT_COMPRESS_MIN_LENGTH; // 5000
if (compressor === undefined || result.content.length < minLength) {
  return ok(result);          // sem compressor / pequeno demais ⇒ cru
}
const compressed = await compressor(result.content, instruction);
if (!compressed.ok) return compressed; // falha do compressor ⇒ err (fail-closed)
return ok({ ...result, content: compressed.value });

const doFetch = config.fetch ?? (globalThis.fetch as unknown as FetchLike); // padrão = global

const postJson = async (doFetch, url, headers, body) => {
  const responded = await tryCatchAsync(() => doFetch(url, { method: 'POST', headers, body }));
  if (!responded.ok) return responded;          // throw de rede ⇒ err
  const response = responded.value;
  if (!response.ok)                              // status não-2xx ⇒ err
    return err(new Error(`web backend HTTP ${response.status} …`));
  return tryCatchAsync(() => response.json());    // JSON inválido ⇒ err
};

// sem Date.now() / Math.random() (a plan VM do motor proíbe ambos);
// o pedido não carrega nonce nem timestamp.

Por isso o backend roda dentro de um alembic.plan.ts sem disparar o detector de não-determinismo: a mesma entrada produz o mesmo pedido, sempre.

O backend devolveu uma linha. O kernel a re-valida. Escolha a linha e veja o veredito — e por que ele falha ou passa:

{ title: "Exemplo",
  url: "https://example.com",
  snippet: "um resultado" }

Simples ↔ Técnico: a mesma ideia, duas alturas

Cartões de memória