98 lines
5.0 KiB
Markdown
98 lines
5.0 KiB
Markdown
# 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. |