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

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, plan.md, research.md, and 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

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)

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)

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)

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.