feat(logic-grid-ai)!: structured validation errors + model option

[antonstefer]

Summary

Three small AI-package improvements bundled into one major bump.

1. Structured validation errors

validateThemeResult now returns ThemeValidationError[] (each with a stable code, human-readable message, and optional category field). validateRewrittenClues returns RewriteCluesValidationError[] with code, message, optional 1-indexed clueIndex. Codes are exported as union types so callers can write exhaustive switches.

generateTheme now throws ThemeGenerationError carrying the structured errors; rewriteClues throws RewriteCluesError. Callers can do:

try {
  await generateTheme({ theme: "...", size: 4, categories: 4 });
} catch (err) {
  if (err instanceof ThemeGenerationError) {
    if (err.errors.some((e) => e.code === "no_ordered_category")) {
      // surface a specific hint to the user
    }
  }
  throw err;
}

2. Model option on createAnthropicClient

createAnthropicClient(undefined, { model: "claude-haiku-4-5" });

Defaults to the existing claude-sonnet-4-6. Backward-compatible — old single-arg call sites still work. Useful for swapping to Haiku for cheaper/faster generation without writing a whole custom AIClient.

3. Documents Anthropic SDK retry behavior

Code comment + README note: transport-level retries (429s, 5xx, network errors) are already handled inside the Anthropic SDK with exponential backoff. Our MAX_RETRIES = 3 only covers semantic validation failures (the AI returned malformed output and we re-prompt with the errors). The two layers don't compound.

Coverage

logic-grid-ai stays at 100% statements / branches / functions / lines (75 tests).

Breaking changes

• validateThemeResult and validateRewrittenClues return structured objects instead of strings.
  • Migration: read e.message for the same human-readable text, or switch to e.code for stable identifiers.
• generateTheme and rewriteClues now throw ThemeGenerationError / RewriteCluesError subclasses instead of plain Error. instanceof Error checks still match — only === against Error itself would change behavior.

Release impact

feat!: triggers a major bump → release-please will propose logic-grid-ai 2.0.0. Worth merging together with the in-flight logic-grid 3.0.0 Release PR (#22) since logic-grid-ai's peerDep on logic-grid is also moving up.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	logic-grid	89eae4f	Commit Preview URL Branch Preview URL	Apr 28 2026, 01:18 PM