Nova Action Event Columns Laravel Package

Technical Evaluation

Architecture fit

• Extends Nova's audit trail rather than introducing a parallel logging system — the action_events table remains the single source of truth for who did what, which keeps existing audit queries, Nova's ActionResource screens, and any downstream reporting intact.
• The column registry is the strategically important feature: it turns a one-off ip_address add-on into a reusable extension point for tenancy, user-agent, request correlation IDs, or compliance tags without forking Nova or maintaining a patched vendor tree.
• Coverage strategy (model creating hook + query-builder insert() override) is deliberately chosen to catch the mass-insert paths (delete, force-delete, restore, custom actions) that bypass Eloquent events. This is the correct problem to solve, but it is also the main architectural coupling.
• Ships its own ActionResource, meaning the package owns a piece of Nova's presentation layer. That is what makes the columns visible with sensible defaults, but it also means we inherit responsibility for that resource staying in step with Nova's own.

Integration feasibility

• Low-friction install for a standard Nova app: publish migration + config + custom-column stub, add columns to action_events, register the resource in NovaServiceProvider. No service container gymnastics, no Nova fork.
• The migration ordering matters. action_events is a Nova-owned table; our additive migration must run after Nova's, and we should treat any future Nova migration touching that table as a potential conflict to re-verify on upgrade.
• The custom-column stub gives a clean path for our first real column (tenant_id is the obvious candidate for multi-tenant installs) without waiting on upstream releases.
• Constraint to plan around: Nova 4 caps at Laravel 11 / PHP 8.4 via its Inertia dependency. If our roadmap includes Laravel 12+ or PHP 8.5, the Nova 5 upgrade is a prerequisite, not a parallel track.

Technical risk

• Vendor-internal coupling (highest). Overriding insert() on Nova's ActionEvent model depends on Nova continuing to route mass inserts through that model. If a future Nova release switches to DB::table('action_events')->insert(), coverage degrades silently — actions still succeed, columns are simply null. Silent audit gaps are the worst failure mode for this class of package.
• Resolver failure semantics (unknown). A registered value resolver throwing inside a creating hook or insert() override could abort the user's action. We need to confirm whether failures are swallowed, logged, or propagated — and set a policy (almost certainly: log and write null, never block the action).
• IP capture correctness. request()->ip() honours TrustProxies. Behind an ALB/Cloudflare, a misconfigured proxy list yields the load balancer's IP for every event — plausible-looking data that is quietly wrong. Verify in staging, not production.
• Privacy/compliance. Persisting IP addresses on every action event turns an internal audit table into personal data. Retention now has a legal dimension, not just a storage one.
• Maturity. v1.0.0 with strong quality signals (100% line coverage, mutation testing MSI ≥ 80%, PHPStan level 8, CI across both Nova majors) reduces — but does not eliminate — the risk of a young package sitting on a closed-source dependency's internals.

Key questions

1. What happens when a value resolver throws — action aborted, or logged and nulled?
2. How does the package detect coverage loss if Nova changes its write path? Is there a test or health check we can run against a Nova upgrade?
3. Does the insert() override preserve batch semantics and per-row values correctly for multi-row inserts, and what is the per-row overhead?
4. Is the custom ActionResource a full replacement for Nova's, and what do we lose or gain in sortable/filterable fields?
5. Does the prune command scope to our app only, or can it reach across tenants/environments?
6. What is the upgrade contract — does the package track Nova majors promptly, and is there a supported version matrix beyond 4/5?

Integration Approach

Stack fit

• Native fit for a Laravel 11/12 + Nova 4/5 application on PHP 8.2–8.4. No new infrastructure, no queue, no external service — everything lands in the existing action_events table.
• For multi-tenant deployments, tenant_id via the column registry is the natural first custom column and likely the single highest-value use of this package beyond IP capture.
• If any part of the estate is on PHP 8.5 or Laravel 12+ with Nova 4, that slice is out of scope until Nova 5.

Migration path

• Additive and reversible: columns are nullable and appended, so there is no backfill obligation and no rewrite of existing rows. Historical events simply have nulls in the new columns — accept and document that boundary.
• Sequence: (1) upgrade to Nova 5 first if the target stack requires it, (2) publish and run the migration in a maintenance-safe window, (3) register the custom ActionResource, (4) enable ip_address in config, (5) add tenant_id via the stub once the base install is proven.
• Rollback is a column drop plus config revert; no data loss beyond the new columns.

Compatibility

• Explicitly verified on Nova 5 (Laravel 11/12/13, PHP 8.3/8.4) and Nova 4 (Laravel 11, PHP 8.4). That is a genuinely useful matrix for a paid, closed-source dependency.
• Confirm our TrustProxies configuration before trusting IP values, and confirm our Nova version is within ^4.0 || ^5.0.
• Watch the interaction between our migration and any Nova-shipped migration on action_events during Nova minor upgrades.

Sequencing

1. Spike in a non-production environment: install, run migration, execute one of each action type (create, update, delete, force-delete, restore, custom action) and verify columns populate on all paths.
2. Deliberately break a resolver and observe behaviour — this determines our error-handling policy.
3. Enable in production with ip_address only, at low blast radius, before adding custom columns.
4. Add tenant_id and any compliance columns once baseline confidence is established.
5. Wire the prune command into the scheduler only after retention policy is agreed.

Operational Impact

Maintenance

• We inherit a dependency on Nova's internals, not just its public API. Budget a recurring line item: re-verify full write-path coverage on every Nova major and minor bump. A cheap harness — one test per action type asserting the registered columns are populated — converts that from manual QA into a regression gate.
• Upstream package maintenance looks healthy (mutation testing, static analysis, dual-major CI), which lowers but does not remove the risk of a young package tracking a closed-source framework.

Support

• Failure presentation is favourable: missing columns degrade to nulls rather than breaking actions, so users will not report outages — they will report missing audit data, possibly months later. Support needs a documented "is the audit trail complete?" check.
• Single-owner bus-factor risk if we extend the column registry heavily; keep custom resolvers in application code, not in a fork, so they remain reviewable by the team.

Scaling

• Per-row resolver execution on mass-insert paths is the scaling consideration. Bulk deletes of thousands of records produce thousands of action events, each invoking every registered resolver. Keep resolvers pure, cheap, and free of I/O — no external lookups per row.
• action_events is already append-only and was going to grow; the added columns are narrow scalars and add negligible row width. The real growth concern is event volume, which the prune command addresses.
• Confirm indexes after adding columns — particularly if tenant_id becomes a common filter in the ActionResource, it likely warrants an index.

Failure modes

• Silent coverage loss after a Nova upgrade — highest severity, mitigated by the per-action-type regression harness above.
• Resolver exception aborting a user's action — unacceptable; must be configured/verified to log and null out.
• Wrong IP captured behind an unconfigured proxy — plausible-looking, quietly incorrect compliance data.
• Over-aggressive pruning deleting audit history needed for an incident review or a compliance window. The production confirmation prompt helps, but the --days policy should be a written decision, not a scheduler default.
• Migration conflict on a Nova upgrade that alters action_events.

Ramp-up

• Low for any developer already fluent in Nova: it is config plus one migration plus an optional resource registration. Half a day to first value.
• The column registry needs a short internal standard — naming, resolver purity, nullability, and Nova field factory conventions — or we will accumulate inconsistent columns across teams.
• Biggest ramp-up cost is organisational, not technical: agreeing the retention window and the personal-data policy for IP capture before the first production event is written.