• 01Idle → screening → job-builder, with /cancel wired once on the screening parent so any sub-state cancels the same way.
• 02The screening AI call is an fromPromise XState actor invoked from evaluating. The machine declares what; the orchestrator provides how.
• 03Verdicts get a permanent page at the dashboard under /screening/[id], an unguessable public share at /s/[slug], an OG card, and a server-rendered Chromium PDF.

The constraint I held myself to: the FSM is the source of truth. Server actions don't mutate state directly. The UI doesn't mutate state. The AI call doesn't mutate state. Everything goes through the machine. That is what makes /cancel work the same way from any sub-state and what makes a page reload put you back exactly where you were.

The thing to look at is the dashed line from the SCREENING parent. That is one transition on the parent state, not four wired to every leaf. XState's hierarchical states are why /cancel from gathering works the same way as /cancel from evaluating. The other piece is fromPromise + AbortSignal: the FSM owns the 60-second timeout, and when it fires, it actually cancels the in-flight model call. ADR 0001 has the full reasoning.

// src/lib/domain/screening.ts
export const screeningResultSchema = z.object({
  candidateName: z.string(),
  role: z.string(),
  verdict: z.enum(["strong", "moderate", "weak", "wrong_role"]),
  score: z.number().int(),
  summary: z.string(),
  mustHaves: z.array(requirementMatchSchema),
  niceToHaves: z.array(requirementMatchSchema),
  strengths: z.array(z.string()),
  gaps: z.array(z.string()),
  recommendation: z.string(),
});

export type ScreeningResult = z.infer<typeof screeningResultSchema>;

// src/lib/ai/screen.ts
const { object } = await generateObject({
  model,
  schema: screeningResultSchema,    // ← LLM constraint
  schemaName: "ScreeningResult",
  system: SYSTEM_PROMPT,
  prompt: buildPrompt(input),
  maxRetries: 2,
});

// src/lib/db/schema.ts
result: jsonb("result").$type<ScreeningResult>(),  // ← DB column type

This is what keeps the LLM honest in production. The model returns a typed ScreeningResultor it throws — there is no parse-the-JSON-and-pray path anywhere in the codebase. If a model can not produce schema-valid JSON after two retries, the FSM's error branch fires and the user sees a friendly error.

const DEFAULT_MODEL = "anthropic/claude-sonnet-4.6";
const modelId = process.env.OPENROUTER_MODEL ?? DEFAULT_MODEL;
const model = openrouter(modelId);

• ✓Same code talks to Anthropic, OpenAI, Google, Mistral, anyone OpenRouter routes to.
• ✓A/B different models with one env var, zero code edits.
• ✓Single key to rotate. Single billing surface.

The model market keeps shifting. When Workfully wants to evaluate GPT-5.4 or Gemini 3 against the same screening prompt, it's a five-minute change instead of a sprint. See ADR 0004 for the full rationale.

• 01Test myFSM, not XState's framework.
• 02Test at the boundary, not the implementation.
• 03Mock at the integration point (provide({ actors })), not deeper in the SDK.
• 04One E2E for "wires connected," not for coverage.
• 05Don't test the model's IQ. That is an eval problem, not a unit-test problem.

The escape hatch I'm proudest of.

When WORKFULLY_FAKE_AI=1 is set, screen() bypasses OpenRouter entirely and runs a 30-line deterministic stub. CI runs Playwright against it: the build does not depend on OpenRouter uptime, the assertions can be precise, and the codepath is unreachable in production because the env var simply is not there.

// src/lib/ai/screen.ts
if (process.env.WORKFULLY_FAKE_AI === "1" && !deps.model) {
  return fakeScreen(input);
}

See ADR 0005 for the full strategy.

Five-job CI on every push:

• ✓lint+typecheck
• ✓test+coverage
• ✓build
• ✓e2e (Playwright + real Postgres service container)
• ✓audit (high-severity prod CVEs)