Performance Laravel Package

Technical Evaluation

Architecture fit v1.1.0 keeps the package's existing shape — service-provider self-registration, feature-keyed agents, and an HTTP surface — and extends it rather than restructuring it, so hosts already running the performance package will recognize the patterns. The two agents (performance.query_insight, performance.optimization_suggestion) follow the aiFeatures() auto-discovery convention from artisanpack-ui/ai, which means no manual wiring in the host's provider. Three parallel trigger surfaces (Livewire, React, Vue) cover the realistic Laravel front-end topologies: Blade/Livewire apps get an out-of-the-box panel, while SPA hosts get components that accept caller-supplied data. The decision to ship React/Vue components inside the performance package rather than in the shared @artisanpack-ui/react / @artisanpack-ui/vue bundles is defensible for coupling reasons but fragments the JS distribution model the team already knows.

The concerning architectural change is the promotion of artisanpack-ui/ai from optional to a hard require. That converts an additive feature release into a dependency the entire installed base inherits, whether or not they enable AI. For a performance-observability package this is a heavier footprint than the feature justifies, and it is the single item most likely to complicate upgrades.

Integration feasibility Feasible but non-trivial. Work required in the host: aligning on artisanpack-ui/ai: ^1.0, publishing/overriding ai_middleware (default ['api', 'auth:sanctum']), deciding whether the default permissive performance.ai.use Gate is acceptable, and configuring model credentials. The 409/412/422/404/403 status taxonomy plus the PerformanceAiError class with status and feature key is genuinely good integration ergonomics — misconfiguration surfaces as a renderable state rather than a parse-the-message exercise. The Livewire OptimizationSuggestionPanel reading performance_metrics directly with MAX_WINDOW_DAYS = 90 / MAX_METRICS_ROWS = 2000 means a working demo in minutes; the React/Vue paths require the host to own metric aggregation, which is more work than the release notes imply.

Technical risk

• Data egress. Query text, EXPLAIN plans, schema, and aggregated metrics leave the application boundary for a third-party model. For anyone in a regulated domain, schema and query bodies routinely contain table/column names that are themselves sensitive. This is the highest-severity item in the release and is not addressed.
• Cost exposure with no caching. Both agents set $cacheable = false. The rationale is sound for a point-in-time diagnostic, but it means every panel render is a full-price model call. Combined with a permissive default Gate (any authenticated user), the package ships a token-burn path with no built-in quota.
• Vendor default. claude-sonnet-4-6 as default model is fine if configurable; the release notes don't state how the host overrides it.
• Prompt injection surface. EXPLAIN plans and schema hints are model input; a hostile or malformed plan is an untrusted input channel.
• Input bounds undefined. The metrics path is bounded; the query-insight path has no stated limit on schema/plan size, so wide schemas can silently exceed context and fail or truncate.

Key questions

1. Can artisanpack-ui/ai be made a suggest rather than a hard require, or is the coupling intentional and permanent?
2. What is the documented config path for swapping the default model, and is per-agent model override supported?
3. Is there a recommended rate-limit / quota pattern on top of the performance.ai.use Gate, or is that entirely the host's problem?
4. What happens on provider timeout or 5xx — which status does the API return? (Not enumerated in the taxonomy.)
5. Is there truncation or validation on schema/EXPLAIN payloads before they reach the model?
6. What is the upgrade guarantee for the shipped React/Vue components — are they versioned with the PHP package's semver, and do they carry peer-dependency expectations?

Integration Approach

Stack fit Assumes Laravel with Sanctum already in play (the default ai_middleware depends on auth:sanctum, and the gate assumes an authenticated user). Livewire hosts get the lowest-friction path — component plus direct metrics read, no aggregation code. Inertia/React and Inertia/Vue hosts get components that expect a caller-supplied metrics batch, which means the host must already have, or build, an aggregation step against performance_metrics. Vanilla JS and any other caller can use PerformanceClient.suggestQueryInsight() / suggestOptimization(). The separately-configured ai_middleware correctly avoids reusing the anonymous Web Vitals ingest stack — that separation is the right call and should be preserved as-is.

Migration path This is an additive minor release, but the artisanpack-ui/ai require promotion makes it an upgrade that must be planned, not floated. Sequence:

1. Dependency audit — resolve artisanpack-ui/ai version against whatever the host already pulls; check for conflicts in a branch, not on the integration environment.
2. Stage an upgrade in a non-production environment with composer update artisanpack-ui/performance and verify the AI package boots cleanly even with AI features off.
3. Publish/adjust ai_middleware config; confirm route registration does not collide with existing /api/performance/* routes.
4. Confirm the performance.ai.use Gate override behavior — the guard is designed so a host-registered override wins, so register one explicitly rather than relying on the permissive default.
5. Validate credentials and the 412 path deliberately (unset the key, confirm the client surfaces it).
6. Smoke-test the API via PerformanceClient before touching any UI components.

Compatibility Watch items: config caching (php artisan config:cache) after adding ai_middleware; CSRF/cookie vs token auth depending on whether React/Vue callers are same-origin SPA or external; and the shipped React/Vue components' bundler expectations, which now live in a PHP-vendored package and therefore sit outside the normal JS dependency graph — verify they resolve through the host's build. Livewire component registration should be automatic via the service provider but is worth a route/list check.

Sequencing Land the dependency and config work first and independently of feature enablement, so a failed upgrade is isolated. Then enable the API surface behind a restrictive Gate, then the Livewire panel (lowest effort, highest signal for validating cost and latency), then React/Vue once the host owns metrics aggregation. Ship the query-insight panel before the optimization panel: it is the more clearly valuable feature and the easier one to evaluate against a human DBA's read.

Operational Impact

Maintenance Two new agent classes plus three trigger surfaces across two JS frameworks inside a PHP package is a meaningful maintenance surface expansion — the team is now tracking prompt/model behavior, not just code. The default model string claude-sonnet-4-6 is pinned in code and will drift; confirm it is config-overridable so model rotation doesn't require a package bump. Upstream artisanpack-ui/ai semver becomes an upgrade gate for the performance package whether or not AI is in use. Budget recurring review time for the dual-framework components.

Support The error taxonomy is the strongest operational asset in this release: 409 disabled, 412 missing credentials, 422 validation, 404 unknown feature, 403 gate denial, all carried through PerformanceAiError with the feature key. First-line support can triage from a status code without reading logs. Gaps to document internally: no stated behavior for provider timeouts or 5xx, and no user-facing distinction between "gate denied" and "quota exhausted" — both will look like 403 unless the host layers a quota signal on top.

Scaling Model latency, not throughput, will set the UX ceiling; panels should be treated as slow operations and be user-initiated rather than rendered on page load. $cacheable = false on both agents means repeated identical diagnoses cost full price every time — worth a host-side dedupe or short-TTL cache keyed on query+plan hash if panels get heavy use. The MAX_WINDOW_DAYS = 90 / MAX_METRICS_ROWS = 2000 bounds are a good defensive default and cap input size, but they cap input, not call volume. The empty-metrics short-circuit correctly avoids a model call for a nil result — good. Concurrency should be assumed to hit the model provider's rate limits before it hits anything in the Laravel app.

Failure modes

• Missing credentials → 412, explicit and renderable (good).
• Feature disabled → 409, explicit (good).
• Empty metrics → no model call, returns a short-circuit result (good).
• Default permissive Gate left in place → silent unbounded spend by any authenticated user (highest operational risk).
• Provider timeout / 5xx → not specified; assume unhandled and plan a fallback UI state.
• Oversized schema or EXPLAIN plan → no stated truncation; will present as a validation or provider error with no operator-facing signal.
• Sensitive schema/query content sent to a third-party model → a policy failure mode, not a runtime one, but the one most likely to cause an incident if it wasn't reviewed before rollout.

Ramp-up Lowest-effort adoption is Livewire + API only, with AI gated to a pilot group; that path needs little beyond composer and credential config. React/Vue adoption adds front-end build work and host-owned metrics aggregation and should be treated as a second phase. The team will need working familiarity with LLM cost controls, credential management, and prompt/agent behavior — this is a new competency for most Laravel teams and should be assigned to someone explicitly rather than absorbed tacitly. Recommend a two-week pilot with a restrictive Gate, cost logging on both agents, and a documented rollback: revert to the prior package version and disable the two feature keys, which the gate and 409 path make clean.