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

# Research: Provider-neutral Artifact Source Taxonomy

## Decision 1: Use one shared descriptor over existing artifact truth, not a new artifact table

- **Decision**: represent provider-neutral artifact lineage through one shared descriptor carried by existing finding, evidence, stored-report, inventory, and review-summary seams.
- **Why**: the repo already stores the underlying truth in `Finding`, `EvidenceSnapshotItem`, `StoredReport`, and `InventoryItem`. A new artifact-source table would duplicate that truth and create lifecycle or ownership questions that the current release does not need.
- **Alternatives considered**:
  - new `artifact_sources` table: rejected because it adds persistence and drift risk with no current-release operator value
  - page-local aliasing only: rejected because it would preserve conflicting summaries across findings, evidence, reports, inventory, and review sections

## Decision 2: Pin exact inventories for `source_family`, `source_kind`, and `source_target_kind`

- **Decision**: keep the initial inventories exact and small.
- **Pinned `source_family` set**:
  - `finding`
  - `stored_report`
  - `evidence_snapshot`
  - `inventory`
  - `operation_run`
- **Pinned `source_kind` set**:
  - `model_summary`
  - `stored_report`
  - `operation_rollup`
  - `inventory_projection`
- **Pinned `source_target_kind` set**:
  - `managed_environment`
  - `governed_subject`
  - `provider_connection`
  - `operation_run`
- **Why**: the repo memory and readiness rules require exact inventories when a package introduces a bounded semantic family. Keeping the set explicit prevents later prep or implementation drift.
- **Alternatives considered**:
  - open-ended family strings with only prose guidance: rejected because readiness analysis can flag vague inventories as premature
  - predeclaring package-output or multi-provider families now: rejected because those values are future-facing and not required by current repo truth

## Decision 3: Standardize `detector_key` and `control_key` placement without creating new registries

- **Decision**: `284` standardizes where `detector_key` and `control_key` live in the shared descriptor and touched view models, but it does not introduce a closed detector catalog or a broader control-catalog expansion.
- **Why**: the repo already has working canonical-control resolution. The real problem is inconsistent placement and summary wording, not the absence of a second registry.
- **Alternatives considered**:
  - detector catalog or detector registry: rejected because it is future-facing and wider than current repo truth
  - control-catalog expansion in the same slice: rejected because `284` is about artifact-source semantics, not broader control governance

## Decision 4: Keep provider-native fields as nested detail

- **Decision**: `finding_type`, `report_type`, raw `policy_type`, provider object types, report domains, and Graph-facing detector detail remain provider-owned nested evidence.
- **Why**: the current release is still Microsoft-first in runtime. The goal is to stop using provider-native fields as top-level platform truth, not to erase them.
- **Alternatives considered**:
  - full generic rewrite of provider detail: rejected because it would over-abstract current repo truth
  - leaving provider-native fields as top-level summary nouns: rejected because that preserves the current artifact interpretation drift

## Decision 5: Inventory type separation should live beside existing inventory metadata helpers

- **Decision**: keep `canonical_type`, `provider_object_type`, and `provider_display_type` close to `InventoryPolicyTypeMeta` and the inventory read model rather than creating a new cross-product taxonomy engine.
- **Why**: `InventoryPolicyTypeMeta` is already the narrowest place where inventory type meaning is derived and displayed.
- **Alternatives considered**:
  - new global type registry for every artifact family: rejected because it is broader than the current inventory-only problem
  - leaving inventory on raw `policy_type`: rejected because it would keep one of the explicit 284 acceptance gaps alive

## Decision 6: Legacy rows should normalize on read, not through backfill

- **Decision**: preserve the candidate's no-backfill rule and normalize legacy artifacts on read or during future writes only.
- **Why**: the repo is still pre-production, but `284` does not need a backfill program to deliver operator and contributor value. Read-time normalization is enough for current artifact families.
- **Alternatives considered**:
  - historical backfill migration: rejected because it adds risk and operational work without increasing the core value of the slice
  - leaving legacy rows unreadable until rewritten: rejected because acceptance requires current Microsoft outputs to remain valid as Microsoft provider sources

## Decision 7: Support or AI alignment stays bounded and package runtime remains deferred

- **Decision**: if `SupportDiagnosticBundleBuilder`, `AiUseCaseCatalog`, or adjacent `source_family` consumers are touched, align them to the pinned source-family nouns only. Keep `package_run_id` optional and nullable; do not create package-execution runtime.
- **Why**: the candidate explicitly says later package execution should be able to build on the descriptor, but `284` must not implement package runtime now.
- **Alternatives considered**:
  - package-output or package-run implementation in the same slice: rejected because it is adjacent future work
  - ignoring existing `source_family` consumers entirely: rejected because they can become a second naming drift if touched later without the 284 vocabulary

## Implementation prerequisites present in current repo truth

- Spec `281` provider-neutral provider-connection scope is already present in repo runtime.
- Spec `282` workspace-first artifact surfaces are already present in repo runtime.
- Spec `283` provider capability registry is already present in repo runtime.

Because those inherited prerequisites are already present on the current branch, the remaining blocker is narrower: runtime work for `284` stays `prerequisite-blocked` until SCOPE-001 ownership compliance for the touched tenant-owned artifact tables is satisfied or explicitly excepted.

## Explicit non-goals carried into design

- no new artifact table or ledger
- no provider framework
- no detector registry
- no full control-catalog expansion
- no package runtime or package-output surfaces
- no historical backfill
- no workspace-first RBAC redesign
- no copy or localization neutralization