TenantAtlas/specs/284-provider-neutral-artifact-source-taxonomy/data-model.md

# Data Model: Provider-neutral Artifact Source Taxonomy

## Existing persisted truth reused

### Finding

Existing persisted finding fields already provide the raw inputs for a provider-neutral descriptor:

- `workspace_id`
- `managed_environment_id`
- `finding_type`
- optional `source`
- `title`
- `status`
- `severity`
- `evidence_jsonb`

`finding_type` and `source` remain persisted provider or artifact detail. `284` adds a shared descriptor over them rather than replacing them as raw evidence.

### EvidenceSnapshotItem

Existing evidence snapshot item fields already provide the current evidence-source seam:

- `workspace_id`
- `managed_environment_id`
- `dimension_key`
- `state`
- `required`
- `source_kind`
- `source_record_type`
- `source_record_id`
- `source_fingerprint`
- `measured_at`
- `freshness_at`
- `summary_payload`
- `sort_order`

`284` extends this seam by adding or deriving a provider-neutral descriptor so `source_record_type` stops acting as the only top-level source identity.

### StoredReport

Existing stored-report truth already includes:

- `workspace_id`
- `managed_environment_id`
- `report_type`
- `payload`
- `fingerprint`
- `previous_fingerprint`

Current report producers already write provider-owned fields such as `provider_key` into payload. `284` lifts the shared lineage fields into the common descriptor without deleting provider-owned detail.

### InventoryItem

Existing inventory truth already includes:

- `workspace_id`
- `managed_environment_id`
- `policy_type`
- `external_id`
- `platform`
- `display_name`
- `meta_jsonb`
- `last_seen_at`
- `last_seen_operation_run_id`

`policy_type` remains provider-owned or legacy artifact detail after `284`; it no longer stands alone as the platform's only artifact type label.

## Pinned initial descriptor inventories

### `source_family`

| Value | Meaning |
|---|---|
| `finding` | artifact lineage originates from a finding or finding-derived summary |
| `stored_report` | artifact lineage originates from a stored report |
| `evidence_snapshot` | artifact lineage is summarized inside an evidence snapshot item or evidence snapshot view model |
| `inventory` | artifact lineage originates from inventory capture or inventory projection |
| `operation_run` | artifact lineage originates from operation-run rollup evidence |

### `source_kind`

| Value | Meaning |
|---|---|
| `model_summary` | summary derived directly from one or more model records |
| `stored_report` | summary or artifact read directly from stored-report persistence |
| `operation_rollup` | summary derived from operation-run history |
| `inventory_projection` | summary derived from inventory read models |

### `source_target_kind`

| Value | Meaning |
|---|---|
| `managed_environment` | artifact summarizes environment-wide state |
| `governed_subject` | artifact describes one governed subject or provider object under the environment |
| `provider_connection` | artifact primarily describes provider-connection state |
| `operation_run` | artifact primarily describes one operation run |

## New derived contracts

### ArtifactSourceDescriptor

Represents the provider-neutral lineage envelope for a finding, evidence summary, stored report, inventory item, or touched review summary.

| Field | Type | Notes |
|---|---|---|
| `source_family` | string | One of the pinned values above |
| `source_kind` | string | One of the pinned values above |
| `workspace_id` | integer | Derived workspace scope anchor for the artifact |
| `tenant_id` | integer | Derived tenant scope anchor for the artifact |
| `provider_key` | string | Provider-neutral contract field; current repo truth emits `microsoft` only |
| `provider_connection_id` | integer or null | Nullable because historical artifacts may not know the connection |
| `managed_environment_id` | integer | Required managed-environment anchor inside the derived workspace and tenant scope |
| `source_target_kind` | string | One of the pinned values above |
| `source_target_identifier` | string or null | Optional stable target identifier such as governed-subject key, record id, or run id |
| `detector_key` | string or null | Standardized field for detector or signal identity; no closed catalog in `284` v1 |
| `control_key` | string or null | Existing canonical-control key when available |
| `package_run_id` | integer or null | Optional future package hook only; remains null in current runtime |

### InventoryTypeDescriptor

Represents the inventory-specific type split.

| Field | Type | Notes |
|---|---|---|
| `canonical_type` | string | Platform-owned type used for top-level summary |
| `provider_object_type` | string | Raw provider object type such as the existing `policy_type` value |
| `provider_display_type` | string | Human-readable provider label for operators |
| `legacy_policy_type` | string or null | Optional carry-forward for old readers or diagnostics |

### ArtifactProviderDetail

Nested provider-owned evidence that stays below the shared descriptor.

| Field | Type | Notes |
|---|---|---|
| `legacy_finding_type` | string or null | Existing `finding_type` where relevant |
| `legacy_report_type` | string or null | Existing `report_type` where relevant |
| `legacy_policy_type` | string or null | Existing inventory or drift `policy_type` where relevant |
| `provider_object_type` | string or null | Raw provider object type |
| `provider_display_type` | string or null | Provider-owned display label |
| `detector_detail` | string or null | Provider-facing detector or signal detail |

### ArtifactSourceViewModel

Shared summary contract used by touched Filament pages and presenters.

| Field | Type | Notes |
|---|---|---|
| `headline` | string | Canonical operator-facing summary |
| `source_descriptor` | `ArtifactSourceDescriptor` | Shared lineage envelope |
| `provider_detail` | `ArtifactProviderDetail` | Nested provider-owned detail |
| `control_summary` | array or null | Derived control label, key, and status when existing resolver provides it |
| `freshness` | array or null | Existing freshness or timing metadata |

## Relationships

- One managed environment can own many findings, evidence snapshot items, stored reports, and inventory items.
- One finding or stored report can contribute one `ArtifactSourceDescriptor` per surfaced summary.
- One evidence snapshot can contain many `ArtifactSourceDescriptor` values, one per item.
- One inventory item can expose exactly one `InventoryTypeDescriptor` and one `ArtifactSourceDescriptor`.
- One tenant-review section can summarize zero or more underlying artifacts but should surface one canonical source summary per summarized item.

## Legacy-read normalization rules

- If a finding has `source = null`, derive `source_family` and `source_target_kind` from `finding_type` plus any qualifying evidence fields.
- If a drift finding only exposes `policy_type`, derive `canonical_type` from `InventoryPolicyTypeMeta` or adjacent subject metadata, keep the raw value as `provider_object_type` or `legacy_policy_type`, and never promote it back to the top-level headline.
- If a stored report payload already includes `provider_key`, reuse it; otherwise default the descriptor to the current provider for the producing service.
- If an evidence summary has no single `source_record_id`, keep `source_target_identifier` nullable and prefer `managed_environment` or `governed_subject` targeting instead of inventing synthetic ids.
- If inventory has no distinct provider display label, fall back to the best available metadata label while keeping `provider_object_type` separate from `canonical_type`.
- If canonical-control resolution returns no control, `control_key` remains null rather than forcing a fake mapping.

## Explicit non-goals for data modeling

- no `artifact_sources` table
- no persisted package-run ledger
- no detector registry table or config catalog
- no control-catalog expansion
- no full rewrite of provider-native fields out of existing tables