TenantAtlas/specs/177-inventory-coverage-truth/data-model.md

Phase 1 Data Model: Inventory Coverage Truth (177)

Existing Persisted Truth

OperationRun as coverage basis

Represents the canonical execution record for inventory syncs and remains the source of per-type sync truth.

Relevant existing fields

• workspace_id
• tenant_id
• type
• status
• outcome
• summary_counts
• failure_summary
• context
• started_at
• completed_at

Relevant existing inventory context shape

• context.inventory.coverage.policy_types
• context.inventory.coverage.foundation_types
• each entry stores at minimum status
• optional fields already supported by InventoryCoverage normalization:
  • item_count
  • error_code

Existing invariant

• InventoryCoverage::fromContext() is the canonical parser for run coverage payload.

InventoryItem

Represents last observed tenant inventory rows and remains the source of current observed-item counts.

Relevant existing fields

• workspace_id
• tenant_id
• policy_type
• external_id
• display_name
• category
• platform
• meta_jsonb
• last_seen_at
• last_seen_operation_run_id

Existing invariant

• Observed rows prove last observation only. They do not by themselves prove current tenant coverage completeness.

InventoryPolicyTypeMeta + capability metadata

Represents product support and capability reference for supported and foundation types.

Relevant existing fields and derived attributes

• type
• label
• category
• platform
• restore
• risk
• foundation flag
• dependency support from CoverageCapabilitiesResolver

Existing invariant

• Capability metadata is product support truth, not tenant coverage truth.

New Derived Runtime Contract

TenantCoverageTruth

Derived runtime contract that answers the operator question: which supported types are currently covered for this tenant, which types need follow-up, and which run establishes that statement.

Proposed fields

• tenant_id
• basis_run_id nullable
• basis_run_outcome nullable
• basis_completed_at nullable
• has_current_coverage_result boolean
• supported_type_count
• succeeded_type_count
• failed_type_count
• skipped_type_count
• unknown_type_count
• follow_up_type_count
• observed_item_total
• rows list of TenantCoverageTypeTruth

Derived invariants

• Exactly one row exists for each supported policy type and foundation type currently in the product support catalog.
• follow_up_type_count = failed + skipped + unknown.
• has_current_coverage_result is true only when a completed inventory-sync basis run with parseable payload exists.
• The basis run is chosen independently from current item counts.

TenantCoverageTypeTruth

Derived row contract for one supported type.

Proposed fields

• type
• segment (policy or foundation)
• label
• category
• platform nullable
• coverage_state (succeeded, failed, skipped, unknown)
• follow_up_required boolean
• observed_item_count
• basis_error_code nullable
• restore_mode nullable
• risk_level nullable
• supports_dependencies boolean

Derived invariants

• follow_up_required is true for failed, skipped, and unknown; false only for succeeded.
• observed_item_count > 0 does not change coverage_state.
• coverage_state = unknown when the type is supported but absent from the basis run payload.
• basis_error_code is allowed only for non-succeeded payload-backed states.

Derived State Family

Coverage state family

This feature introduces one derived state family for tenant coverage rows:

• Succeeded
  • the basis run reported the type as successfully processed
• Failed
  • the basis run reported the type as attempted and failed
• Skipped
  • the basis run reported the type as intentionally skipped or not processed during that run
• Unknown
  • no current coverage result exists for the supported type in the basis run

Behavioral consequence

• Failed, Skipped, and Unknown all suppress calm claims and increment follow-up counts.
• Unknown is derived, not persisted.

Relationships

• One TenantCoverageTruth resolves for one tenant at a time.
• One TenantCoverageTruth may reference zero or one basis OperationRun.
• One TenantCoverageTruth contains one row per supported product type from InventoryPolicyTypeMeta::supported() and InventoryPolicyTypeMeta::foundations().
• Each TenantCoverageTypeTruth joins one supported type to zero or one payload-backed status from the basis run and zero or more InventoryItem rows from the current tenant observation set.

Selection Rules

Basis run selection

• candidate runs are OperationRun rows where:
  • tenant_id matches the selected tenant
  • type = inventory_sync
  • status = completed
• candidates are ordered by:
  • completed_at DESC
  • id DESC
• the selected basis run is the first candidate whose context.inventory.coverage payload can be parsed by InventoryCoverage::fromContext()
• if no candidate qualifies, the tenant has no current coverage basis run

Unknown derivation

• if a supported type is absent from both policy_types and foundation_types in the selected basis payload, the type is Unknown
• absence from the basis payload is not converted into Skipped
• item presence from older runs does not upgrade Unknown

Validation Rules

• No schema migration is required.
• No new persisted state is introduced.
• Coverage rows must remain tenant-scoped.
• Capability metadata must not alter the derived coverage state.
• Surfaces may cite the basis run only when they can do so without violating authorization.