TenantAtlas/specs/230-findings-notification-convergence/research.md

Research: Findings Notification Presentation Convergence

Decision 1: Extend the existing OperationUxPresenter seam instead of creating a notification framework

Decision: Reuse App\Support\OpsUx\OperationUxPresenter as the shared anchor for operator-facing database notification presentation and extend it with one bounded shared contract for the in-scope consumers.

Rationale: OperationRunCompleted already proves that the repository has one real shared presenter path for this interaction family. Extending that seam solves the current drift with the smallest change and follows XCUT-001 without introducing a new registry, interface family, or universal notification platform.

Alternatives considered:

• Create a new notification presenter package or registry. Rejected because only three real consumers are in scope and the spec explicitly forbids broader framework work.
• Apply local copy changes in each notification class. Rejected because that would leave the shared interaction family without one explicit contract and would allow drift to continue.

Decision 2: Standardize the primary structure only, not every metadata field

Decision: The shared contract will standardize title, body, one status emphasis with the existing Filament icon treatment, one primary action, and optional supporting lines. Existing domain-specific metadata remains namespaced and secondary.

Rationale: Findings notifications and operation notifications carry different domain truth. The operator needs one stable primary card structure, not one flattened metadata model. Keeping finding_event, reason_translation, and related diagnostic fields secondary preserves current domain fidelity without fragmenting the card grammar.

Alternatives considered:

• Normalize all notification metadata into one new envelope. Rejected because it adds unnecessary semantic machinery and risks losing useful domain-specific context.
• Leave metadata and structure fully local. Rejected because primary structure drift is the operator problem this spec is solving.

Decision 3: Preserve canonical deep-link helpers and plane-specific route resolution

Decision: Continue to source finding links from FindingResource::getUrl(...), admin operation links from OperationRunLinks, and platform operation links from SystemOperationRunLinks.

Rationale: The feature is about presentation convergence, not route ownership. Existing helper seams already encode the correct tenant, admin, tenantless, and system-plane behavior, so the shared contract must consume them rather than replace them.

Alternatives considered:

• Build URLs inline inside the shared presenter. Rejected because it would duplicate existing routing truth and make access bugs more likely.
• Collapse platform and admin operation destinations into one route family. Rejected because the spec requires the current plane-specific destination behavior to stay intact.

Decision 4: Keep the existing Filament drawer and persistence artifacts unchanged

Decision: The feature will keep the current Filament database-notification drawer, the existing notifications table, and the current asset and polling behavior unchanged.

Rationale: The operator problem is inconsistent card grammar, not missing surfaces or storage. Reusing the current shell avoids scope creep and keeps the change inside the intended cleanup boundary.

Alternatives considered:

• Build a new notification center or work queue. Rejected because it adds a second collection surface that the spec explicitly forbids.
• Add new persistence for shared presentation. Rejected because the shared contract is derived and does not represent new product truth.

Decision 5: Prove convergence through focused feature and guard tests only

Decision: Add one contract-level notification test, extend current findings and operations notification tests, and update the existing legacy-notification guard for both local-bypass prevention and the preserved FR-015 boundary.

Rationale: The proving burden is payload structure and route safety across current consumers. Feature-level assertions already cover these concerns and are the narrowest executable proof.

Alternatives considered:

• Add browser coverage. Rejected because the Filament drawer shell itself is unchanged and browser cost would not prove more than payload-level feature tests.
• Rely only on the legacy guard. Rejected because the guard can catch bypass patterns but cannot prove that the rendered payload structure stayed aligned across all current consumers.

Decision 6: Preserve operation-completed guidance and reason translation as secondary context

Decision: OperationRunCompleted keeps its terminal presentation logic, summary lines, and ReasonPresenter output, but these remain secondary supporting context under the shared primary structure.

Rationale: Terminal run notifications carry more diagnostic signal than findings or queued runs. The shared contract should unify the card grammar without erasing the extra detail that makes completed-run notifications actionable.

Alternatives considered:

• Flatten completed-run detail into the same minimal body as queued notifications. Rejected because it would reduce useful operator signal on terminal outcomes.
• Keep completed-run notifications fully separate because of richer detail. Rejected because that would leave the current interaction-family drift unresolved.