TenantAtlas/specs/177-inventory-coverage-truth/spec.md

Feature Specification: Spec 177 - Inventory Coverage Truth

Feature Branch: feat/177-inventory-coverage-truth
Created: 2026-04-05
Status: Draft
Input: User description: "Spec 177 - Inventory Coverage Truth"

Spec Scope Fields (mandatory)

• Scope: tenant + canonical-view
• Primary Routes:
  • /admin/inventory-items and inventory item detail routes while a tenant context is active
  • /admin/coverage while a tenant context is active
  • /admin/operations and /admin/operations/{run} for canonical inventory-sync drill-through
• Data Ownership:
  • Tenant-owned InventoryItem rows and per-type observed item counts remain the tenant inventory observation truth.
  • Workspace-owned OperationRun rows with a tenant reference remain the canonical execution truth for inventory_sync, including the existing per-type payload stored under context.inventory.coverage.
  • Product capability and support metadata remain derived from the supported-type catalog and capability metadata already exposed through inventory policy-type meta and related capability resolvers.
  • This feature introduces no new persisted coverage table, no materialized coverage snapshot, and no writeback artifact.
• RBAC:
  • Workspace membership, tenant entitlement, and tenant inventory view capability remain required for the inventory items list and the coverage page.
  • Starting an inventory sync from the inventory items list remains gated by the canonical tenant inventory sync capability.
  • Inventory-sync run drill-through remains governed by existing operation-run authorization: workspace membership, tenant entitlement when a run is tenant-bound, and any run-specific required capability already attached to that run.
  • Coverage surfaces must never expose broken or unauthorized next-action links; when a user can see coverage truth but cannot open the backing run, the UI must degrade safely.

For canonical-view specs, the spec MUST define:

• Default filter behavior when tenant-context is active: Coverage-to-operations navigation opens the exact latest relevant inventory-sync run when one is available. If the operator needs the broader operations list instead, the canonical destination opens prefiltered to the active tenant and the inventory-sync operation family.
• Explicit entitlement checks preventing cross-tenant leakage: Coverage summary counts, per-type rows, observed-item counts, run references, and follow-up actions must be derived only from the active tenant scope and from operation runs the current user is entitled to inspect. Non-members remain deny-as-not-found, and inaccessible runs must not leak existence through clickable dead ends.

UI/UX Surface Classification (mandatory when operator-facing surfaces are changed)

Surface	Surface Type	Primary Inspect/Open Model	Row Click	Secondary Actions Placement	Destructive Actions Placement	Canonical Collection Route	Canonical Detail Route	Scope Signals	Canonical Noun	Critical Truth Visible by Default	Exception Type
Inventory items list with KPI summary	Read-only Registry / Report Surface	Full-row click to inventory item detail remains the one inspect model for item records	required	Run Inventory Sync stays in the header; coverage and run continuity links stay in the KPI summary or adjacent summary content	none	/admin/inventory-items	Inventory item detail route for the selected tenant item	Active tenant context, current filters, and the last relevant sync reference anchor the list to one tenant	Inventory Items / Inventory Item	Observed items plus truthful tenant coverage summary, including latest sync reference and follow-up counts rather than a misleading restorable-item percentage	Embedded summary surface inside a read-only resource
Inventory coverage page	Read-only Registry / Report Surface	The page itself is the canonical tenant coverage report; diagnostics drill through via explicit summary links to the relevant sync run	forbidden	Summary-level diagnostic and retry actions live above or beside the per-type table; capability reference remains secondary on the page	none	/admin/coverage	/admin/operations/{run} for the cited relevant inventory-sync run	Active tenant context, cited run timestamp, cited run identity, and visible succeeded or failed or skipped or unknown counts	Inventory Coverage	Per-type tenant coverage truth, follow-up need, and the run the truth is based on, clearly separated from product capability reference	Derived per-type rows have no standalone record detail
Inventory sync run detail	Detail-first Operational Surface	Dedicated run detail page	forbidden	Existing back, refresh, related-link, and safe diagnostic actions remain in the detail header	none	/admin/operations	/admin/operations/{run}	Workspace context, referenced tenant, run timing, run outcome, and inventory-sync identity	Inventory Sync Run / Operation Run	Execution outcome plus human-readable per-type coverage results instead of raw JSON alone	none

Operator Surface Contract (mandatory when operator-facing surfaces are changed)

Surface	Primary Persona	Surface Type	Primary Operator Question	Default-visible Information	Diagnostics-only Information	Status Dimensions Used	Mutation Scope	Primary Actions	Dangerous Actions
Inventory items list with KPI summary	Tenant operator	List with embedded summary	What has this tenant inventory observed, and does current coverage need follow-up before I trust that view?	Total observed items, last relevant sync reference, counts of succeeded types and types needing follow-up, and the inventory item list itself	Raw run context, low-level provider failure details, and secondary capability metadata	coverage truth, execution recency, item presence	Run Inventory Sync continues to affect the Microsoft tenant and TenantPilot inventory observation state; the list itself is read-only	Open inventory item, Run Inventory Sync, Open coverage truth	none
Inventory coverage page	Tenant operator	Derived report	Which supported types are currently covered for this tenant, which are not, and what should I do next?	Coverage summary, follow-up summary, cited relevant sync, and a per-type table showing state, timestamp or run reference context, observed item count, and follow-up need	Secondary support or capability reference, dependency capability, raw reason codes, and deep diagnostics	coverage truth, execution truth, item presence, capability reference as a separate domain	none on the report itself; any sync retry action keeps the existing inventory-sync mutation scope	View latest sync run, Run inventory sync again when authorized, Review follow-up types	none
Inventory sync run detail	Tenant operator or workspace operator with tenant entitlement	Detail	What did this inventory sync actually do per type, and how does that explain the tenant's current coverage truth?	Run status and outcome, human-readable per-type results, counts, related tenant context, and next-step guidance	Full context JSON, raw failure payloads, and deeper technical fragments	execution outcome, per-type coverage result, item counts, next-step guidance	none on the detail page itself	Refresh, open related coverage context, open related records	none

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: No.
• New persisted entity/table/artifact?: No.
• New abstraction?: Yes, one narrow derived coverage-truth assembler or read model may be required to combine supported types, the latest relevant inventory-sync result, observed item counts, and follow-up classification on existing surfaces.
• New enum/state/reason family?: Yes, a narrow derived tenant-coverage state family must include Unknown or Not synced yet alongside the existing successful, failed, and skipped outcomes. It remains derived, not persisted.
• New cross-domain UI framework/taxonomy?: No.
• Current operator problem: Operators currently see a Coverage KPI that is really a restorable-item share, while real per-type sync truth lives in inventory-sync run context and is almost invisible on the operator-facing surfaces that should answer coverage questions.
• Existing structure is insufficient because: The KPI widget currently compresses restorable-item share into Coverage %, the coverage page renders a capability or support matrix rather than tenant sync truth, and inventory-sync run detail does not expose per-type results in an operator-first format.
• Narrowest correct implementation: Derive one tenant coverage view from the existing latest relevant inventory-sync run, the supported-type catalog, and current inventory-item counts; surface it on the existing inventory pages and inventory-sync run detail; keep product capability reference secondary; add no new persistence.
• Ownership cost: Focused derived-read-model logic, presentation cleanup on three existing surfaces, and regression coverage across tenant coverage, operations drill-through, and RBAC-safe degradation.
• Alternative intentionally rejected: A new coverage table, a restore-readiness score, a compare-readiness layer, a dashboard-wide inventory health program, or a broader content-depth taxonomy were rejected because the immediate defect is misleading operator truth on already-shipped inventory surfaces.
• Release truth: Current-release truth correction that prepares later usefulness, missing-item, and dashboard follow-up work.

User Scenarios & Testing (mandatory)

User Story 1 - Read truthful coverage at a glance (Priority: P1)

As a tenant operator, I can open inventory surfaces and immediately understand which supported inventory types are currently covered for my tenant and which types still need follow-up.

Why this priority: The current trust failure starts at first glance. If the leading KPI and coverage page are semantically wrong, every later decision is biased by false calm.

Independent Test: Can be fully tested by seeding one tenant with a latest relevant inventory-sync run that contains a mix of succeeded, failed, skipped, and omitted types plus current inventory items, then rendering the inventory items list and the coverage page.

Acceptance Scenarios:

1. Given a tenant has a latest relevant inventory-sync run with mixed per-type outcomes, When the operator opens the coverage page, Then every supported type appears with a truthful state of succeeded, failed, skipped, or unknown and the follow-up summary highlights the non-succeeded types.
2. Given a supported type has observed items but no current coverage result in the relevant sync basis, When the operator opens the coverage surface, Then the type appears as unknown or not synced yet rather than implicitly covered.
3. Given no relevant inventory-sync run exists for the tenant, When the operator opens the inventory summary surfaces, Then the UI makes clear that there is no current coverage result and points the operator toward starting inventory sync instead of presenting a positive coverage claim.

---

User Story 2 - Move cleanly from coverage truth to run truth (Priority: P1)

As a tenant operator, I can see which inventory-sync run the current coverage statement is based on and open that run or a safe equivalent diagnostic path without losing tenant context.

Why this priority: Coverage claims must be recoverable. If the UI states that a tenant is covered or not covered but cannot show the exact run that established that claim, the truth is not auditable.

Independent Test: Can be fully tested by seeding a tenant with a relevant inventory-sync run and verifying that the coverage page and inventory summary surfaces cite the run, the timestamp, and the correct drill-through behavior for both authorized and unauthorized viewers.

Acceptance Scenarios:

1. Given current coverage is derived from a specific inventory-sync run, When the operator opens the coverage page, Then the page shows the cited run and timestamp and provides a direct path to that run.
2. Given the current user can see inventory truth but cannot open the backing run, When the coverage page renders, Then the page shows safe explanatory guidance instead of a broken or unauthorized run link.
3. Given the operator needs the broader operations history, When the operator follows the diagnostic path from inventory coverage, Then the operations destination stays scoped to the originating tenant and the inventory-sync operation family.

---

User Story 3 - Diagnose per-type inventory-sync results without raw JSON (Priority: P2)

As a tenant operator, I can open an inventory-sync run detail page and read the per-type results in human terms, so I understand how execution outcome and coverage follow-up relate.

Why this priority: The backend already knows this truth. The missing value is readable diagnosis, not a new execution system.

Independent Test: Can be fully tested by seeding an inventory-sync run whose per-type payload contains mixed outcomes and verifying that the run detail page renders a readable per-type breakdown and next-step guidance without requiring raw JSON inspection.

Acceptance Scenarios:

1. Given an inventory-sync run has per-type coverage payload data, When the operator opens the run detail page, Then the page shows a human-readable per-type result section rather than burying the truth only in raw context JSON.
2. Given the run outcome is partially successful, When the operator views run detail, Then the page separates overall execution outcome from the specific types that still need follow-up.
3. Given one or more types failed or were skipped, When the operator views run detail, Then the next-step guidance points to the relevant follow-up path such as reviewing provider or permission problems or running inventory sync again.

Edge Cases

• The tenant has never completed a relevant inventory-sync run, so all supported types must remain unknown instead of reading as covered by default.
• The latest relevant run omitted one or more supported types entirely, which must result in unknown rather than silent success.
• Observed items exist from an older run, but the latest relevant run did not establish current coverage truth for that type.
• The latest relevant run failed or was blocked before processing most or all selected types.
• A type was intentionally skipped because of selection or foundation toggles, and the UI must show that truth without implying success.
• The current user may view inventory surfaces but may not satisfy the required capability for the cited inventory-sync run.
• The supported-type catalog may change after the latest sync, so the coverage surface must distinguish current support reference from tenant sync truth.

Requirements (mandatory)

Constitution alignment (required): This feature introduces no new Microsoft Graph contract, no new change operation, and no new long-running workflow. It reuses the existing inventory_sync operation truth already written into canonical OperationRun records and corrects how that truth is surfaced on inventory pages.

Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001): The feature is intentionally narrow. It introduces no new persistence and no generic framework. A single derived coverage-truth assembler and one derived Unknown coverage state are justified because the existing surfaces currently misrepresent three different truths as one. The feature follows the default bias of deriving before persisting, replacing misleading semantics before layering new ones, and being explicit instead of generic.

Constitution alignment (OPS-UX): The existing inventory_sync OperationRun remains canonical. This feature does not change queued-toast, progress-surface, or terminal-notification behavior. OperationRun.status and OperationRun.outcome remain service-owned through OperationRunService, summary_counts remain numeric-only and canonical, scheduled or system-run behavior is unchanged, and regression coverage must verify run-detail rendering and coverage-to-run continuity without inventing new operation feedback surfaces.

Constitution alignment (RBAC-UX): This feature spans tenant inventory surfaces on /admin with active tenant context and canonical operations surfaces on /admin/operations. Non-members or actors outside the current tenant scope remain 404. In-scope members missing the required run capability remain 403 on the run detail itself. Server-side authorization remains the source of truth through the existing capability resolver on inventory surfaces and OperationRunPolicy plus run-capability resolution for run drill-through. No raw capability strings or role-string checks are introduced. No new destructive action is added.

Constitution alignment (OPS-EX-AUTH-001): Not applicable. No authentication handshake behavior is changed.

Constitution alignment (BADGE-001): Any added or updated coverage-state badges must stay centralized. Succeeded, Failed, Skipped, and Unknown must use shared badge semantics rather than page-local color language, and regression tests must cover the new or revised mappings.

Constitution alignment (UI-FIL-001): The feature reuses Filament stats widgets, tables, sections, badges, infolists, and actions already present on the affected inventory and operations surfaces. It avoids local replacement markup for status language and does not require publishing internal Filament views. No exception is expected.

Constitution alignment (UI-STD-001): The modified inventory items list and inventory coverage page are governed by docs/product/standards/list-surface-review-checklist.md, and implementation must review both surfaces against that checklist before sign-off.

Constitution alignment (UI-NAMING-001): Operator-facing vocabulary must distinguish Coverage, Support, Capability, Restore mode, Compare, Last sync, and Needs follow-up. Coverage means tenant-specific sync coverage for supported types. Coverage % is forbidden unless explicitly qualified as the latest sync's type coverage. Restore ready and Compare ready must not be used as synonyms for coverage.

Constitution alignment (UI-CONST-001 / UI-SURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001): The inventory items list keeps row click for real inventory records. The inventory coverage page remains a derived report with an approved exception: its per-type rows do not open a standalone detail record. Diagnostics drill through through explicit links to the relevant run. The canonical collection and detail routes are stated above, and critical truth visible by default must be tenant coverage truth rather than support metadata.

Constitution alignment (OPSURF-001): Default-visible content must stay operator-first. Coverage truth, execution truth, and item presence must be shown as separate dimensions. Capability and support metadata remain diagnostics or secondary reference. The existing Run Inventory Sync action continues to communicate a tenant-affecting sync over the external tenant plus TenantPilot observation state and follows the existing safe execution pattern.

Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001): Direct mapping from one existing source is insufficient because current truth is split across operation-run context, inventory-item counts, and supported-type metadata. This feature may introduce one narrow derived coverage view, but it must replace the misleading KPI and capability-centric interpretation rather than add a new general semantic framework. Tests must focus on operator consequences: truthful summaries, safe follow-up, and auditable continuity.

Constitution alignment (Filament Action Surfaces): The Action Surface Contract remains satisfied with one approved exception on InventoryCoverage: derived per-type rows do not have a standalone record detail. Redundant View actions remain absent, empty action groups remain absent, and no new destructive action is introduced. UI-FIL-001 is satisfied with no approved exception beyond the existing derived-row detail exemption.

Constitution alignment (UX-001 - Layout & Information Architecture): The inventory coverage page remains a search and filter driven table surface with a truthful summary above the table and a clear single empty-state CTA. The inventory items list remains a read-only list and detail flow. Inventory-sync run detail remains a view-style operational page. Any new summary panels or diagnostic sections must use shared sections or cards and keep raw JSON secondary.

Functional Requirements

• FR-177-001: Default-visible inventory summary surfaces MUST NOT present a KPI or label that can be read as tenant inventory completeness when it actually represents restorable-item share, capability coverage, or any other secondary truth. The current unqualified Coverage % must be removed or replaced with an explicitly qualified type-coverage statement.
• FR-177-002: The tenant coverage report MUST show every supported inventory type for the selected tenant with, at minimum, the type, current coverage state, the relevant sync reference or time basis, observed item count, and whether follow-up is needed.
• FR-177-003: Coverage state MUST be derived from real inventory-sync truth and MUST include at least Succeeded, Failed, Skipped, and Unknown or Not synced yet.
• FR-177-004: Coverage surfaces MUST make clear which relevant inventory-sync run they are based on, including a visible timestamp and a direct or safely degraded path to the canonical run detail. If no relevant sync exists, the surface must say so plainly.
• FR-177-005: Run execution truth and coverage truth MUST remain separate. A partial or failed run outcome must not replace the per-type statement of which supported types are currently covered and which still need follow-up.
• FR-177-006: The inventory coverage page MUST primarily answer the tenant question Which supported types are currently inventoried successfully for this tenant, and where are the gaps? It must not remain centered on a product support matrix.
• FR-177-007: Product support and capability metadata MAY remain available only as a clearly secondary reference layer with labels such as Support, Capability, or Restore mode. It must not be confused with tenant coverage truth.
• FR-177-008: When one or more supported types are failed, skipped, or unknown, the coverage surfaces MUST prominently signal that follow-up is required, how many types are affected, and which types are highest priority to review first. Follow-up priority MUST use a deterministic severity-first order of Failed before Unknown before Skipped, then observed item count descending, then inventory type label ascending for stable ties.
• FR-177-009: A supported type without a current tenant coverage result MUST appear as Unknown or Not synced yet. It must not appear positively because items exist, because the type is supported, or because the product has richer capability metadata for it.
• FR-177-010: Observed item counts MUST remain clearly separate from coverage truth and MUST NOT be styled or worded as proof of completeness, restore usefulness, or compare usefulness.
• FR-177-011: Coverage surfaces MUST provide real next actions such as viewing the latest relevant run, running inventory sync again, reviewing failed or skipped types, or reviewing provider or permission issues. When a next action cannot be opened by the current user, the surface MUST show safe explanatory guidance instead of a dead-end link.
• FR-177-012: Inventory-sync run detail MUST expose per-type results in a human-readable section and MUST NOT rely on raw JSON alone to communicate which supported types succeeded, failed, or were skipped.
• FR-177-013: All coverage signals, per-type states, counts, and run drill-throughs MUST remain tenant-scoped and RBAC-conformant.
• FR-177-014: Coverage MUST NOT imply restore readiness. Any restore metadata shown on the same surface must remain explicitly separate from the coverage statement.
• FR-177-015: Coverage MUST NOT imply compare readiness. Any compare-related context shown on the same surface must remain secondary and explicitly distinct from coverage truth.
• FR-177-016: The feature MUST be derived from existing inventory items, supported-type metadata, and canonical inventory-sync run truth without adding a new coverage persistence model or rewriting the inventory-sync backend.

UI Action Matrix (mandatory when Filament is changed)

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 items list with KPI summary	app/Filament/Resources/InventoryItemResource.php, app/Filament/Resources/InventoryItemResource/Pages/ListInventoryItems.php, app/Filament/Widgets/Inventory/InventoryKpiHeader.php	Run Inventory Sync	Existing one-click open path to inventory item detail remains the only inspect model for item rows	none	none	Existing inventory list empty-state CTA remains unchanged	n/a	n/a	existing only for sync dispatch	KPI labels, summary facts, and coverage or run continuity links are changed by this spec. The sync action remains capability-gated and non-destructive.
Inventory coverage page	app/Filament/Pages/InventoryCoverage.php	none; summary-level diagnostic or retry CTAs may appear above the table	Approved exception: derived per-type rows do not have a standalone detail record	none	none	Clear filters	n/a	n/a	no new audit behavior	Action Surface Contract remains satisfied through the approved derived-row exception. Run continuity is provided through explicit summary links rather than row inspect actions.
Inventory sync run detail	app/Filament/Pages/Operations/TenantlessOperationRunViewer.php and the existing operation-run detail rendering stack	Existing back, refresh, and related-link header actions remain	Direct page	n/a	none	n/a	Existing back, refresh, and related-link header actions remain	n/a	no new audit behavior	This spec adds human-readable per-type inventory coverage results to the existing detail page and does not introduce new mutations.

Key Entities (include if feature involves data)

• Tenant coverage truth: The tenant-specific statement of whether each supported inventory type is currently covered successfully, failed, skipped, or still unknown.
• Relevant inventory-sync run: The latest completed inventory_sync execution for the active tenant that contains parseable context.inventory.coverage truth. Overall run outcome does not disqualify it when usable per-type payload exists, because Failed and Skipped remain meaningful operator truth.
• Coverage state: The per-type result family used for operator decisions: Succeeded, Failed, Skipped, and Unknown or Not synced yet.
• Observed item count: The current number of inventory items observed for one supported type in the selected tenant, kept separate from coverage truth.
• Capability reference: Static product support metadata such as support mode, restore mode, dependency capability, risk, or similar type metadata that must remain distinct from tenant coverage truth.

Success Criteria (mandatory)

Measurable Outcomes

• SC-177-001: In seeded regression scenarios, the default-visible inventory items summary, inventory coverage page, and inventory-sync run detail together expose covered versus follow-up types, basis-run context, and next-step guidance without requiring raw JSON inspection.
• SC-177-002: In regression coverage, 100% of default-visible inventory summary surfaces stop showing an unqualified Coverage % or any equivalent metric that can be read as tenant inventory completeness.
• SC-177-003: In regression coverage, every supported type shown on the tenant coverage report resolves to exactly one of Succeeded, Failed, Skipped, or Unknown, and the summary follow-up count matches the number of non-succeeded types.
• SC-177-004: In tested authorization scenarios, operators can either open the cited relevant inventory-sync run from coverage surfaces or receive a safe non-clickable explanation in 100% of cases.
• SC-177-005: The feature ships without a required schema migration, without a new coverage table, and without a rewrite of the inventory-sync backend.

Assumptions

• Existing inventory-sync runs already persist per-type successful or failed or skipped truth for attempted types inside canonical OperationRun context.
• The supported and foundation type catalog remains the authoritative denominator for tenant coverage reporting.
• Unknown is a derived tenant state used when current coverage truth for a supported type cannot be established from the relevant sync basis, even if older items still exist.
• Inventory item list and detail pages remain the correct places for item-level observation; this spec does not promote them into restore-readiness or compare-readiness surfaces.

Non-Goals

• Redesigning the backup or restore domain
• Introducing a restore-readiness algorithm or item-level readiness score
• Introducing a compare-readiness domain for inventory coverage
• Building a missing or vanished item workflow
• Launching a dashboard-wide inventory health program
• Adding a new persistence table or materialized coverage artifact
• Rewriting the inventory-sync backend

Dependencies

• Spec 039 - Inventory Program
• Spec 040 - Inventory Core
• Spec 041 - Inventory UI
• Spec 042 - Inventory Dependencies Graph
• Existing inventory surfaces, inventory-sync execution, supported-type metadata, and canonical operations drill-through behavior already present in the repo

Follow-up Spec Candidates

• Inventory Content Depth & Usefulness: Separate coverage truth from content depth, restore usefulness, and compare usefulness.
• Inventory Missing / Vanished Surface: Add explicit follow-up for missing or vanished items once coverage truth is no longer overloaded.
• Dashboard Inventory Health: Propagate truthful coverage and freshness signals onto broader tenant overview surfaces after the core coverage semantics are corrected.

Definition of Done

Spec 177 is complete when:

• no operator can read a default-visible coverage metric as tenant inventory completeness when it is actually describing capability or restorable-item share,
• the inventory coverage page shows truthful per-type tenant coverage and makes follow-up obvious,
• the inventory items list and its KPI summary cite truthful coverage and last-sync context rather than a misleading percentage,
• inventory-sync run detail exposes per-type results in human-readable form,
• capability and support metadata remain available but secondary and explicitly labeled,
• coverage-to-run continuity is auditable and RBAC-safe,
• and the improvement ships without a new persisted coverage model or an inventory-sync backend rewrite.