Ia Exception Bundle Laravel Package

Technical Evaluation

Architecture fit. This is a Symfony bundle, not a framework-agnostic PHP library. It attaches at kernel.exception, resolves an agent service ID (ai.agent.default) from the Symfony AI container, renders through a Twig error template, and registers config under a darkwood_ia_exception tree in YAML. Laravel has no equivalent extension points: no bundles, no kernel.exception, no Twig-by-default, no service-ID-based agent resolution. Architectural fit for a Laravel codebase is effectively zero for direct installation. The pattern — intercept 5xx, fingerprint and cache, call an LLM with sanitized exception context, degrade silently on failure — fits Laravel fine and is implementable in bootstrap/app.php + withExceptions() plus a queued job.

Integration feasibility. Three viable routes, in ascending order of ownership:

The bundle's own logic surface is small — a listener, a prompt builder, a cache fingerprint, one async controller. Option C is realistic. The expensive dependency is not this package but symfony/ai-bundle, which the changelog shows moved through ^0.6 → ^0.8 → ^0.10 → ^0.12 within a few months. That pre-1.0 churn, not the exception bundle, is the schedule risk.

Technical risk.

• Platform mismatch: PHP 8.5+ and Symfony 8.x are bleeding-edge requirements that will conflict with typical Laravel estates on PHP 8.2–8.4.
• Diagnostic trust: an LLM-produced "probable cause" is a hypothesis presented next to a real stack trace. Hallucinated causes can send engineers down wrong paths during an incident — the exact moment judgment is worst.
• Cost/latency shape: AI spend correlates with error volume, which spikes precisely during outages. Sync mode (async: false) blocks kernel.exception and directly extends user-facing 500 latency.
• Data exposure: exception messages routinely contain SQL fragments, table/column names, file paths, and occasionally tokens. The bundle sends class, message, file, line (and trace if enabled) to a third-party LLM. That is a vendor data-processing question, not just a config toggle.
• Async endpoint: GET /__ai_exception/{error_id} returns analysis of a real production error. It ships unauthenticated by default; it needs auth, rate limiting, and a documented retention policy for async_context_ttl.
• Prompt injection: exception messages can contain attacker-influenced content; low severity if the page is developer-facing only, non-trivial if surfaced to end users.
• Supply chain: 2 stars, 0 dependents, single maintainer, releases mirroring Symfony patch versions. No third-party validation exists; we would be adopter #1.

Key questions.

1. Who is the audience — internal engineers only, or end users seeing the 500 page? This changes the risk tier completely.
2. Is the goal reduced MTTR or improved error-page UX? Only the former justifies LLM cost.
3. Which LLM vendor, under what DPA, and is exception text permitted to leave our boundary?
4. What is the per-incident cost ceiling, and who owns the budget line?
5. Do we accept a pre-1.0 AI SDK dependency in a production path?
6. Is porting (Option C) acceptable, or is vendor-package installation a hard requirement?

Integration Approach

Stack fit. Not installable on Laravel. Treat this repository as a specification and reference implementation rather than a dependency. The valuable, portable pieces are: the fingerprint-based cache key (exception class + message + top frames), the fail-safe contract ("never set a response if AI fails"), the sanitization allowlist (class/message/file/line only), and the async-with-graceful-fallback UX.

Migration path. Do not attempt coexistence. If a spike is needed, stand up a throwaway Symfony 8.1 app in a sandbox to observe real output quality on 20–30 representative production exceptions before writing any Laravel code. That test answers the only question that matters — is the analysis actually useful — independent of framework.

Compatibility. Hard blockers if installing: PHP 8.5, Symfony 8.x, symfony/ai-bundle ^0.12, and a configured platform + agent with a scoped HTTP client to enforce timeout_ms. Versioning is confusing: the project uses unified Darkwood versioning at 1.3.0 and then jumps to 8.x to track Symfony patch releases, so constraint management is a manual exercise. Expect upgrade pressure every Symfony patch.

Sequencing.

1. Spike (1 wk): sandbox Symfony app, replay anonymized exceptions, score output usefulness and sanitization quality.
2. Decision gate: if output is not materially better than the existing stack trace, stop.
3. Design (1 wk): Laravel-native design — withExceptions hook, allowlisted context extractor, cache key, queue-based async, auth + rate limit on any retrieval endpoint, vendor DPA.
4. Build (1–2 wks): implement Option C behind a feature flag, staging only, include_trace permanently false, hard concurrency and spend caps, circuit breaker to a plain 500 page.
5. Pilot (2–4 wks): staging then internal-only production surface, measured on MTTR delta and cost per resolved incident, not on subjective page quality.

Operational Impact

Maintenance. Upstream is a satellite of a monorepo and inherits its release cadence (8.1.0 → 8.1.1 → 8.1.2 → 8.1.3 in short succession). Consuming it means tracking Symfony patch releases and pre-1.0 AI SDK breaking changes. Porting (Option C) trades that for owning ~500 lines of code plus the LLM integration — usually the better trade; the AI SDK integration is the part we would have to own anyway.

Support. No dependents and a single maintainer under MIT mean no support contract and no community troubleshooting corpus. Budget for the first adopter's tax: our own debugging, our own runbooks. If the maintainer stops, the fork cost is small but non-zero, and there is no CVE-watch coverage for a package this obscure.

Scaling. Cost and latency scale linearly with novel error volume. Caching by fingerprint collapses repeated errors (default 600s TTL) but provides no help during a first-of-its-kind incident, when cache hit rate is ~0% and every distinct error fans out to a separate LLM call. Mitigations must be first-class: queue with capped workers, per-minute spend ceiling, circuit breaker that disables enrichment after N consecutive failures or budget exhaustion.

Failure modes and required behavior.

Ramp-up. Reading and configuring the bundle is roughly half a day; the real cost is the surrounding platform work — secret management for the LLM key, scoped HTTP client with enforced timeouts, vendor onboarding and DPA, and on-call training to treat generated output as a labeled hypothesis rather than a diagnosis. Plan for one engineer-week of enablement plus an explicit "do not trust, verify" convention in the incident runbook.

Recommendation. Do not adopt as a dependency in a Laravel estate — the framework and PHP-version constraints make it non-viable, and 0 dependents/2 stars means no external validation. Fund a one-week sandbox spike to test whether LLM error diagnosis actually reduces MTTR on our own exception corpus, and if it does, build a Laravel-native equivalent reusing the bundle's fail-safe contract, sanitization allowlist, and fingerprint caching. Gate production rollout on a measured MTTR delta, a hard spend ceiling, and a completed vendor data review.