Determinismo e replay: o mesmo input, o mesmo run

o id do run é a impressão digital do spec

Na orquestração, o runId é literalmente derivado do spec via runIdFor (que vive em ./ids.js). Não há leitura de relógio nem chamada a um gerador aleatório: o mesmo spec sempre dá o mesmo id, e qualquer mudança de campo dá um id novo.

import { runIdFor } from './ids.js';
// …
const runId = runIdFor(spec);   // impressão digital (hash) do spec
// mude qualquer campo de `spec` ⇒ runId diferente ⇒ diretório de run diferente

endereçamento por conteúdo nos stores também

A mesma ideia reforça os stores append-only: cada registro carrega o SHA-256 do seu JSON canônico (chaves ordenadas recursivamente), então "re-acrescentar conteúdo idêntico é um no-op". A idempotência é estrutural — rodar duas vezes não duplica.

// - CONTENT-ADDRESSED: cada registro carrega o SHA-256 do seu JSON canônico;
//   re-acrescentar conteúdo idêntico é um no-op (dedupe por hash).
const canonicalJson = (value) => { /* chaves ordenadas recursivamente */ };
const hash = sha256Hex(canonicalJson(payload));   // a mesma estrutura ⇒ o mesmo hash

dois ids, dois propósitos

freshId é literalmente randomUUID() — não-determinístico de propósito — e o worker o usa para requestId (correlação de logs). A regra é: o que identifica um run deriva do conteúdo (runIdFor); o que só correlaciona pode ser aleatório (freshId). Confundir os dois quebraria a reprodutibilidade.

import { createHash, randomUUID } from 'node:crypto';
// identidade do run: derivada do conteúdo (determinística)
export const runIdFor = (spec) => createHash('sha256') /* …spec canônico… */;
// id de correlação: aleatório (NÃO-determinístico) — nunca nomeia um run
export const freshId = (): string => randomUUID();

o caminho é uma função pura de (baseDir, runId)

O diretório é resolvido por resolveRunDir, que só junta baseDir + 'runs' + runId. Nenhuma data, nenhum acaso: dado o mesmo runId, o mesmo caminho. Os runs ficam num namespace próprio, separados de planos, cursos, skills e stores.

/** Constrói o caminho absoluto do diretório de um run. */
export const resolveRunDir = (baseDir: string, runId: string): string =>
  join(expandTilde(baseDir), 'runs', runId);
// o diretório guarda os journals append-only: events.jsonl, checkpoint.json, …

a regra está escrita em dois lugares

A doutrina está no CLAUDE.md do repositório, e é repetida no troubleshooting — para que tanto humanos quanto agentes a vejam. É a mesma postura fail-closed da lição 26: o caminho seguro é o padrão.

- **Determinism:** plan modules (`alembic.plan.ts`) must not use
  `Date.now()`, `new Date()` or `Math.random()`. The VM rejects them.
- **Non-determinism error** — remove `Date.now()`, `new Date()`,
  `Math.random()` from the plan module.

uma varredura por regex, fail-closed

O check é descrito como uma "verificação leve de determinismo, segura para TypeScript": uma varredura por regex pelas três construções. Não é um sandbox que executa o plano — é uma análise de texto, propositalmente conservadora ("um falso positivo é mais seguro que permitir não-determinismo num run retomável"). Se o módulo termina em .ts, o check roda; se acha algo, o carregamento do plano vira um err — o run para.

// Verificação leve de determinismo, segura p/ TS: varre os construtos proibidos.
const forbidden = [
  { pattern: /\bDate\.now\s*\(/,      name: 'Date.now()' },
  { pattern: /\bnew\s+Date\s*\(\s*\)/, name: 'new Date()' },
  { pattern: /\bMath\.random\s*\(/,   name: 'Math.random()' },
];
// …se algum casar:
return err(`plan module ... is non-deterministic: ${determinism.reason}`);

tempo é um valor que entra pela porta

O Clock é só um () => number (epoch ms). O comentário do tipo é explícito sobre o porquê: o default de produção embrulha o relógio real, mas o plano não pode usar Date.now()/new Date() porque "isso quebra o replay". O curator guarda seus limiares em milissegundos justamente para que o Clock injetado seja a única fonte de tempo.

// Uma fonte de tempo monotônica, em epoch ms. O default de produção
// embrulha o relógio real; NÃO use Date.now()/new Date() no código de
// plano — isso quebra o replay.
export type Clock = () => number;

o id da pergunta também é injetado

O construtor aceita uma idFactory opcional; quando ausente, usa o monotonicIdFactory() padrão — nunca um global de acaso. No teste, passa-se monotonicIdFactory('q') e as perguntas ganham ids previsíveis (q-1, q-2, …), tornando o fluxo de clarify reproduzível.

// default = um contador monotônico; nunca um global aleatório
this.mintId = options.idFactory ?? monotonicIdFactory();
// …
export const monotonicIdFactory = (prefix = 'clarify'): (() => ClarifyId) => { /* contador */ };