feat(ai): error taxonomy + fail-fast retry classification (Phase 1 · Batch 1.1)

[qnbs]

User description

Context

Phase 1 (Reliability/Observability) of the v1.23 audit/perfection engagement, first batch.
Recon corrected the sub-baseline: the Local-AI/Voice low-end stack is already built; the real
gap is AI error handling — withTransientRetry retried every error (a bad API key, a
policy block, a 4xx) with exponential backoff.

What this PR does (backend + tests only)

• services/ai/aiErrorTaxonomy.ts — pure classifyAiError(err) → { category, retryable, messageKey } across transient | rateLimit | auth | network | offline | policy | invalidRequest | permanent. Classifies by HTTP status, by message markers (reuses the aiPolicy.ts "blocked" strings), and short-circuits on navigator.onLine === false. Unknown errors default to retryable transient (preserves prior behavior).
• services/ai/aiRetry.ts — withTransientRetry now fails fast on non-retryable categories (invalid key / policy / malformed request / offline) instead of backing off a doomed call. Transient/rate-limit/network still retry and honor Retry-After. Emits one structured ai.retry log line per decision with a per-call correlation id (no payloads or keys — respects sanitizeLogContext). New optional shouldRetry lets callers override.
• Tests (+33): aiErrorTaxonomy.test.ts (table-driven over every category + offline short-circuit + status-beats-message); fail-fast + shouldRetry-override cases in aiRetry.test.ts; logger stubbed in the 3 retry test files for deterministic output.
• Docs: living plan batch log + CHANGELOG.md [Unreleased].

Scope notes

• Backward compatible: the two consumers (aiProviderService.ts:437,471) keep working; the new option is optional and unknown errors still retry.
• messageKey UI/i18n mapping deferred to Batch 1.2 (avoids 11-locale churn here).
• FU-1 (plugin-worker guard restoration) split out of this batch after a timeboxed probe: the Function.prototype.constructor leak is real but its mechanism is subtler than a symmetric defineProperty fix; it's benign (the worker compiles via the captured GlobalFunction) and is documented in docs/AUDIT-PERFECTION-PLAN-v1.23.md for a dedicated fix.

Verification

• pnpm exec vitest run taxonomy + all retry suites + plugin.worker → 90 passed.
• pnpm run lint (1312 files) + pnpm run typecheck → clean.
• git diff --name-only → only the taxonomy, retry, 3 retry tests, and 2 docs (no production source beyond aiRetry).

🤖 Generated with Claude Code

---

CodeAnt-AI Description

Stop retrying AI calls that cannot succeed and add clear error classification

What Changed

• AI errors are now grouped into clear categories so retry handling can tell apart temporary failures, rate limits, network problems, auth issues, policy blocks, invalid requests, and offline states
• Retry now stops immediately for non-retryable errors like invalid API keys, policy blocks, malformed requests, and offline mode instead of waiting and trying again
• Retryable AI failures still back off and keep honoring server-provided retry delays
• Each retry decision now produces a structured log entry, and callers can override the default retry decision when needed
• Added tests for error classification, fail-fast behavior, custom retry overrides, and deterministic retry logging

Impact

✅ Fewer repeated failed AI calls
✅ Faster errors for bad keys, policy blocks, and offline users
✅ Clearer AI failure handling

💡 Usage Guide

Checking Your Pull Request

Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.

Talking to CodeAnt AI

Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:

@codeant-ai ask: Your question here

This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.

Example

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

Preserve Org Learnings with CodeAnt

You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:

@codeant-ai: Your feedback here

This helps CodeAnt AI learn and adapt to your team's coding style and standards.

Example

@codeant-ai: Do not flag unused imports.

Retrigger review

Ask CodeAnt AI to review the PR again, by typing:

@codeant-ai: review

Check Your Repository Health

To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.

[codeant-ai]

CodeAnt AI is reviewing your PR.

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
storycraft-studio	Ready	Preview, Comment	Jun 13, 2026 11:59am

[codeant-ai]

CodeAnt AI finished reviewing your PR.