TenantAtlas/specs/124-inventory-coverage-table/spec.md

Feature Specification: Inventory Coverage Interactive Table

Feature Branch: 124-inventory-coverage-table
Created: 2026-03-08
Status: Draft
Input: User description: "Upgrade inventory coverage from static HTML to an interactive Filament table"

Spec Scope Fields (mandatory)

• Scope: tenant
• Primary Routes: /admin/t/{tenant}/inventory/coverage tenant-scoped Inventory Coverage page in the Inventory cluster
• Data Ownership: Workspace-owned coverage metadata derived from the existing inventory policy type registry and capability resolver, rendered inside a tenant-scoped page without introducing new tenant-owned storage
• RBAC: Existing tenant membership and tenant inventory viewing entitlement remain required for page access; this feature does not introduce new permissions or broaden access

User Scenarios & Testing (mandatory)

User Story 1 - Find Supported Policy Types Quickly (Priority: P1)

As a prospect or tenant admin reviewing product capability, I can search the coverage page by policy type or label and immediately narrow the list to the relevant rows.

Why this priority: Fast discovery is the core job of the page. If users cannot find a policy type quickly, the page fails as both a demo surface and an operational lookup tool.

Independent Test: Can be fully tested by loading the coverage page with multiple policy types, searching for a partial type or label, and confirming that only matching rows remain while coverage badges stay visible.

Acceptance Scenarios:

1. Given a tenant user with access to Inventory Coverage and multiple supported policy types, When they search by a partial type or label, Then the table shows only matching rows.
2. Given a search result set, When the user clears the search, Then the full coverage list returns without losing badge semantics or grouping context.

---

User Story 2 - Filter Coverage by Meaningful Dimensions (Priority: P2)

As a governance or operations user, I can filter coverage by category and, when present in the current data shape, by restore mode so that I can evaluate support boundaries without manually scanning every row.

Why this priority: Filtering is the next most important behavior after search because it turns the page into a practical evaluation tool instead of a static reference sheet.

Independent Test: Can be tested by applying a category filter and confirming that only matching rows appear, then verifying that a restore-mode filter is available only when the loaded data contains restore-mode values.

Acceptance Scenarios:

1. Given coverage rows across multiple categories, When the user selects a category filter, Then only rows from that category remain visible.
2. Given restore-mode data exists in the current row shape, When the user selects a restore-mode filter, Then only rows with that restore characteristic remain visible.
3. Given restore-mode data is not available in the current row shape, When the user opens the page, Then the page omits that filter rather than showing a broken or misleading control.

---

User Story 3 - Present Coverage as a Product-Grade Surface (Priority: P3)

As a sales, demo, or evaluation user, I can scan the page as a polished product surface that looks consistent with the rest of the application rather than a raw developer table.

Why this priority: This feature is a trust surface. Visual consistency and scanability materially affect confidence during demos and product evaluation, but they depend on the core discovery behaviors above.

Independent Test: Can be tested by loading the page in both light and dark modes, confirming that the table uses native product patterns, presents clear empty states, and preserves existing badge semantics.

Acceptance Scenarios:

1. Given the user opens Inventory Coverage, When the page loads, Then the coverage content appears in a first-class interactive table experience aligned with other admin list pages.
2. Given the page is viewed in dark mode, When the user scans the table, filters, and badges, Then text, controls, and status cues remain readable and visually consistent.

Edge Cases

• When a search or filter combination returns no rows, the page shows a specific empty state with a short explanation and exactly one clear action to reset the table state.
• When restore-mode metadata is missing for some or all rows, the page still renders correctly and only exposes a restore-mode filter if the current data shape supports it.
• When both supported policy types and foundation types are shown, users can still understand which rows belong together without duplicating or weakening existing metadata semantics.

Requirements (mandatory)

Constitution alignment (required): This feature is read-only. It introduces no Microsoft Graph calls, no write behavior, no queue or schedule behavior, and no OperationRun usage.

Constitution alignment (RBAC-UX): This feature stays on the tenant admin plane under the existing tenant-scoped Inventory Coverage page. Authorization behavior does not change: current tenant membership and existing tenant-view capability checks remain the server-side gate, and no new access pathways are introduced.

Constitution alignment (BADGE-001): Existing badge semantics for policy type, category, restore mode, risk, and dependency indicators remain centralized in the current badge catalogs or equivalent shared badge mapping. This feature may change presentation layout, but it must not introduce page-local badge labels, colors, or icons.

Constitution alignment (Filament Action Surfaces): This feature requires an explicit exemption from the record-inspection affordance portion of the Action Surface Contract. Coverage rows are runtime-derived support metadata, not first-class records with a meaningful detail route, so the page intentionally provides native table search, sort, filters, and an explicit resettable empty state without clickable rows or row actions.

Constitution alignment (UX-001 — Layout & Information Architecture): The page remains inside the existing Filament page structure, uses native table interactions for core dimensions, provides a specific empty state with exactly one reset action, and preserves dark-mode readability. No exemption is required.

Functional Requirements

• FR-001: The Inventory Coverage page MUST replace the current raw static HTML tables with a Filament-native interactive table experience.
• FR-002: Users MUST be able to search the coverage table by policy type and human-readable label.
• FR-003: Users MUST be able to sort by the primary type or name column.
• FR-004: Users MUST be able to filter coverage rows by category.
• FR-005: Users MUST be able to filter coverage rows by restore mode when that attribute exists in the current data shape.
• FR-006: The page MUST preserve the current meaning of badges and status indicators for type, category, restore mode, risk, and dependency support.
• FR-007: The page MUST continue using the current coverage data sources and metadata assumptions rather than redefining the inventory coverage model.
• FR-008: The page MUST remain visually aligned with other list and table experiences in the application, including dark mode.
• FR-009: The page MUST provide an explicit empty state for zero-result searches or filters with exactly one action that returns the user to a populated view.
• FR-010: The page MUST remain read-only and MUST NOT add mutation, sync, or comparison behaviors as part of this feature.

UI Action Matrix (mandatory when Filament is changed)

If this feature adds/modifies any Filament Resource / RelationManager / Page, fill out the matrix below.

For each surface, list the exact action labels, whether they are destructive (confirmation? typed confirmation?), RBAC gating (capability + enforcement helper), and whether the mutation writes an audit log.

Surface	Location	Header Actions	Inspect Affordance (List/Table)	Row Actions (max 2 visible)	Bulk Actions (grouped)	Empty-State CTA(s)	View Header Actions	Create/Edit Save+Cancel	Audit log?	Notes / Exemptions
Inventory Coverage page	app/Filament/Pages/InventoryCoverage.php	None	Explicit exemption: no inspect affordance because rows are runtime-derived metadata with no meaningful detail route	None	None	Clear filters	None	Not applicable	No	Read-only tenant page; exemption applies only to record inspection, while search/sort/filter and empty-state UX remain required

Key Entities (include if feature involves data)

• Coverage Entry: A single supported policy type or foundation row containing the stable policy type identifier, human-readable label, category, dependency support signal, restore mode, and risk semantics.
• Coverage Segment: A logical grouping of coverage entries that distinguishes the supported-policy surface from the foundation surface while still letting users search and filter effectively.
• Coverage Metadata Catalog: The shared registry-derived metadata and badge semantics that define how coverage attributes are labeled and visually represented across the application.

Assumptions

• The existing coverage row shape continues to provide policy type, label, category, dependency support, and risk semantics.
• Restore mode remains optional in the current data shape. Implementation and tests must cover both branches with deterministic runtime fixtures: at least one dataset where restore values exist and the filter is rendered, and one dataset where restore values are absent and the filter is omitted.
• The current tenant-scoped page access rules and Inventory cluster placement remain unchanged.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: A user can locate a specific policy type on a populated coverage page in 15 seconds or less using search and table controls.
• SC-002: A user can narrow the page to a target category in two interactions or fewer.
• SC-003: In manual demo review, a stakeholder can identify restore capability and dependency support for a filtered set of policy types without verbal guidance from the presenter.
• SC-004: Manual dark-mode QA finds no unreadable text, broken filter controls, or badge contrast regressions on the coverage page.