TenantAtlas/specs/321-alerts-audit-log-environment-filter-contract-decision/decision.md

Spec 321 Decision: Alerts / Audit Log Environment Filter Contract

Status: Draft decision artifact Date: 2026-05-17 Branch: 321-alerts-audit-log-environment-filter-contract-decision

Decision Summary

Alerts and Audit Log remain Workspace-owned surfaces.

The canonical Environment filter key is:

environment_id

No legacy aliases are accepted. No remembered Environment fallback is accepted. No Filament tenant fallback is accepted.

Surface Decisions

Surface	Current behavior	Data model supports environment attribution?	Chosen contract	Reason	Implementation impact	Test impact
Alerts overview / Alert Center	Registered workspace hub, but Spec 318 found /admin/alerts?environment_id=... redirects/drops query or lacks full filter contract.	Partially, through environment-attributable alert delivery signal. Alert rules/destinations are workspace configuration.	environment_filterable_workspace_hub	Alerts are an operational signal hub. Operators need "show me alerts for this Environment" behavior, and the delivery signal has reliable managed_environment_id.	Resolve canonical environment_id, show shared chip, scope environment-attributable KPI/signal data, keep shell Workspace-only, clear with shared resetter.	Clean URL, filtered URL, visible chip, clear, reload, legacy alias rejection, cross-workspace guard.
Alert Deliveries	Registered workspace hub/table resource. Has current table filter for managed_environment_id, but no canonical visible workspace-hub chip contract.	Yes. alert_deliveries.managed_environment_id exists, is nullable, workspace-constrained, and indexed.	environment_filterable_workspace_hub	Deliveries are the table-backed alert event/signal surface and can be filtered without inference.	Apply canonical environment_id to query/table state using shared resolver, render chip, clear stale Filament/session table filters.	Filtered rows prove data scope; clear and reload safety; legacy aliases ignored.
Alert Rules	Registered under Alerts. Workspace configuration surface. Uses workspace-level rule configuration, including targeting settings.	No page-level filter attribution. Rule targeting config is not the same as page ownership/filter state.	configuration_workspace_surface	Rules configure workspace alert behavior and should not appear Environment-owned or Environment-filtered.	Do not render chip. Do not accept environment_id as filter state. Keep clean links from navigation/CTAs.	Assert environment_id does not create chip/filter and Environment CTAs do not emit filters to this surface.
Alert Destinations	Registered under Alerts. Workspace configuration surface.	No. Destinations are workspace notification targets.	configuration_workspace_surface	Notification destinations are workspace-level configuration, not Environment-scoped operational signal.	Do not render chip. Do not accept environment_id as filter state. Keep clean links from navigation/CTAs.	Assert environment_id does not create chip/filter and Environment CTAs do not emit filters to this surface.
Audit Log	Registered workspace hub. Spec 318 found /admin/audit-log?environment_id=... preserves query but shows no visible chip.	Yes. audit_logs.managed_environment_id exists, is nullable, indexed, and tied to workspace attribution.	environment_filterable_workspace_hub	Audit Log is a workspace governance surface, but many records are reliably Environment-attributable. Filtering by direct attribution is useful and safe.	Resolve canonical environment_id, filter by audit_logs.managed_environment_id, render chip, keep shell Workspace-only, clear stale query/table/session state.	Clean URL, filtered URL, visible chip, filtered rows, selected event consistency, clear, reload, legacy alias rejection, cross-workspace guard.
Audit event detail / selected event state	Same Audit Log page, usually selected through query/state.	Yes when the selected event row has managed_environment_id.	environment_filterable_workspace_hub	Event detail is metadata inside the Audit Log surface, not a separate Environment-owned page.	If a filter is active, selected event state must remain inside the filtered query scope or be neutralized. Show Environment metadata as event data, not shell ownership.	Assert selected event outside active Environment filter is not shown as the selected detail.
Environment Dashboard CTAs to Alerts / Alert Deliveries / Audit Log	Must be inspected during implementation.	Yes for the filterable destinations above.	environment_filterable_workspace_hub destinations use canonical environment_id.	Environment-origin navigation may preserve Environment focus only when the destination supports the full filter contract.	Add or update links to use environment_id only. No legacy params.	Assert CTAs use canonical environment_id and no legacy aliases.
Environment Dashboard CTAs to Alert Rules / Alert Destinations	Must be inspected during implementation.	No page-level filter attribution.	configuration_workspace_surface destinations use clean workspace links or are omitted.	Configuration surfaces should not imply Environment-specific state.	Remove Environment filter params from these destinations.	Assert CTAs emit no Environment filter params.

Final Contract Values

Allowed values used in this decision:

environment_filterable_workspace_hub
configuration_workspace_surface

No surface in scope remains ambiguous.

Runtime Constraints

• Shell remains Workspace-only for all surfaces in this decision.
• Filterable surfaces accept only environment_id.
• Legacy aliases are invalid as Environment filter input.
• Cross-workspace or unauthorized Environment IDs must be rejected safely.
• Clear behavior must remove URL, table, deferred table, session, and page Environment filter state.
• No migrations are expected.

Reopen Conditions

Update this decision before implementation continues if:

• Runtime discovery shows audit_logs.managed_environment_id or alert_deliveries.managed_environment_id is not reliable.
• A migration or new persisted attribution field becomes necessary.
• A new Alert or Audit sub-surface is discovered that cannot be classified by this artifact.