# Quickstart: Provider-neutral Artifact Source Taxonomy

## Purpose

Use this guide to review or later implement Spec `284` as one bounded artifact-source and inventory-type taxonomy slice.

## Preconditions

1. Specs `281`, `282`, and `283` are already present on the implementation branch.
2. Work stays inside `apps/platform` and this spec package.
3. No application implementation from Specs `285` through `287` is pulled into this slice.
4. No historical backfill or package runtime is added.
5. SCOPE-001 ownership compliance for touched tenant-owned artifact tables is resolved or explicitly excepted before runtime implementation begins.

## Pinned descriptor inventories

- `source_family`:
  - `finding`
  - `stored_report`
  - `evidence_snapshot`
  - `inventory`
  - `operation_run`
- `source_kind`:
  - `model_summary`
  - `stored_report`
  - `operation_rollup`
  - `inventory_projection`
- `source_target_kind`:
  - `managed_environment`
  - `governed_subject`
  - `provider_connection`
  - `operation_run`

## Reviewer flow

1. Read [spec.md](./spec.md), [plan.md](./plan.md), [research.md](./research.md), and [data-model.md](./data-model.md) together.
2. Confirm the package introduces one shared artifact-source descriptor and one inventory type split, not a new artifact table.
3. Confirm the pinned inventories above for `source_family`, `source_kind`, and `source_target_kind` are identical across all artifacts.
4. Confirm provider-native detail such as `finding_type`, `report_type`, `policy_type`, and provider object types remains nested evidence instead of top-level platform truth.
5. Confirm `package_run_id` stays optional and unused in current runtime.
6. Confirm the logical contract and feature proof preserve inherited `404` versus `403` behavior for the touched resources.
7. Confirm reviewer and proof guidance explicitly cover `workspace_id`, `tenant_id`, `managed_environment_id`, `provider_connection_id`, and `source_target_identifier` semantics when those fields are available.

## Suggested implementation order

1. Add the bounded descriptor support seam and pin the exact inventories.
2. Update findings, evidence-source providers, and stored-report readers or writers to carry the descriptor.
3. Update inventory metadata to expose `canonical_type`, `provider_object_type`, and `provider_display_type`.
4. Update touched Filament resources and review presenters to show descriptor-first summaries.
5. Align touched support or AI `source_family` consumers only if needed.
6. Run the exact bounded proof commands below.

## Narrow proof commands

```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && \
  (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact \
    tests/Unit/Artifacts/ArtifactSourceTaxonomyCatalogTest.php \
    tests/Unit/Inventory/InventoryCanonicalTypeDescriptorTest.php)
```

```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && \
  (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact \
    tests/Feature/Artifacts/FindingArtifactSourceTaxonomyTest.php \
    tests/Feature/Artifacts/EvidenceSnapshotSourceTaxonomyTest.php \
    tests/Feature/Artifacts/StoredReportSourceTaxonomyTest.php \
    tests/Feature/Artifacts/InventoryArtifactTypeTaxonomyTest.php \
    tests/Feature/Filament/Artifacts/ArtifactSourceTaxonomySurfaceTest.php \
    tests/Feature/Guards/ArtifactSourceProviderTruthGuardTest.php)
```

```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && \
  (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact \
    tests/Browser/Spec284ArtifactSourceTaxonomySmokeTest.php)
```

```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && \
  (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail bin pint --dirty --format agent)
```

## Expected smoke path

1. Open one finding and confirm the page shows the canonical source descriptor before provider-native detail.
2. Open one evidence snapshot or evidence item tied to the same managed environment and confirm the same source-family and control summary semantics are visible.
3. Open one stored report and confirm it uses the same descriptor-first disclosure while keeping raw `report_type` nested.
4. Open one inventory item and confirm `canonical_type`, `provider_object_type`, and `provider_display_type` are separate.
5. Open one tenant review with supporting artifact sections and confirm the section summary stays aligned with the underlying artifact descriptor.

## Stop conditions

- Stop if implementation tries to add a new artifact table or ledger.
- Stop if implementation introduces a detector catalog or expands into a control-catalog initiative.
- Stop if implementation requires historical backfill or dual-write compatibility.
- Stop if `policy_type`, `finding_type`, or `report_type` returns as the primary summary noun on touched surfaces.
- Stop if package runtime, copy neutralization, or RBAC redesign starts appearing inside the same slice.