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

Feature Specification: Provider-neutral Artifact Source Taxonomy

Feature Branch: 284-provider-neutral-artifact-source-taxonomy
Created: 2026-05-08
Status: Implementation Ready
Input: User description: "Follow the next-best-prep workflow for reserved slot 284 and prepare the Provider-neutral Artifact Source Taxonomy v1 package without implementing application code."

Implementation Acceptance Update (2026-05-09): Runtime implementation is now explicitly requested. The prior SCOPE-001 prerequisite block is resolved for this slice by repo truth: Specs 281, 282, and 283 are present on the implementation branch, Spec 279 records the approved managed-environment core exception, and the touched artifact tables now carry the established workspace plus managed-environment ownership boundary. No new table, ownership plane, descriptor columns, or backfill is introduced by this status update.

Spec Candidate Check

• Problem: TenantPilot already stores and renders artifact truth through finding_type, source, report_type, policy_type, source_kind, provider-owned payload fields, and ad hoc canonical-control bindings, but those seams still let Microsoft-specific type names behave like platform-core truth. Findings, evidence snapshots, stored reports, inventory metadata, and review sections describe the same artifact lineage in parallel vocabularies instead of one provider-neutral source contract.
• Today's failure: Operators and contributors must reinterpret the same artifact through different discriminator families. FindingsSummarySource treats permission_posture, entra_admin_roles, and deviceCompliancePolicy as if they were interchangeable core-domain truth; StoredReport persists report_type as the main summary noun; EvidenceSourceProvider only exposes source_kind plus raw record type or id; and inventory still treats policy_type as the top-level metadata key even where the platform already differentiates governed-subject vocabulary from provider-owned detail.
• User-visible improvement: Findings, evidence, reports, inventory items, and review or support summaries expose one canonical source descriptor first: source family, target, detector, and control summary. Microsoft-specific object types, report types, Graph-facing detector details, and legacy policy_type values remain available, but they become provider-owned detail instead of the first thing an operator or contributor must decode.
• Smallest enterprise-capable version: Introduce one bounded artifact-source descriptor across existing finding, evidence, stored-report, and inventory seams; pin the initial source_family, source_kind, and source_target_kind inventories; separate inventory canonical_type, provider_object_type, and provider_display_type; and align touched evidence or review presenters to disclose the canonical descriptor before provider detail. Do not add a new artifact table, no compliance engine, no full detector catalog, no control-catalog expansion, and no historical backfill.
• Explicit non-goals: No new compliance engine, no full control-catalog expansion, no historical backfill, no provider framework, no package-execution runtime, no workspace-first RBAC rewrite from Spec 285, no copy or localization neutralization from Spec 286, no no-legacy enforcement pack from Spec 287, and no UI-polish-first redesign.
• Permanent complexity imported: One bounded artifact-source descriptor contract, one pinned inventory for source_family, source_kind, and source_target_kind, one narrow normalizer or presenter seam if existing helpers cannot carry the contract cleanly, one inventory type descriptor split, and focused unit, feature, guard, and browser proof. No new table or independent persisted entity is imported.
• Why now: Specs 279 through 283 already moved the platform toward workspace-first managed environments, provider-neutral connection scope, artifact-surface ownership, and provider capability truth. The remaining gap is artifact lineage and artifact-type semantics. If 284 does not land now, later package-output work and later copy neutralization will still inherit Microsoft-shaped artifact truth.
• Why not local: The drift is shared across models, evidence-source contracts, stored-report readers, inventory metadata, review sections, and operator surfaces. A local rename in one page or one service would immediately diverge from the other artifact consumers.
• Approval class: Core Enterprise
• Red flags triggered: New taxonomy, new shared abstraction, and derived descriptor scope fields. Defense: the repo already has multiple real consumers and conflicting artifact vocabularies. 284 is intentionally bounded to one descriptor contract, a small pinned inventory, and the minimum surface convergence needed to make current-release artifacts provider-neutral.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve

Spec Scope Fields

• Scope: workspace, tenant
• Primary Routes:
  • workspace-first findings resource list and detail surfaces
  • workspace-first evidence snapshot list and detail surfaces
  • workspace-first stored-report list and detail surfaces
  • workspace-first inventory item list and detail surfaces
  • workspace-first tenant-review detail surfaces and shared review sections that already summarize canonical controls and supporting evidence
• Data Ownership:
  • Finding, EvidenceSnapshotItem, StoredReport, and InventoryItem remain tenant-owned persisted truth bound to the established workspace plus tenant scope at authorization time; current repo truth reaches that scope through existing workspace_id columns where present and through managed_environment_id relations everywhere else
  • the shared artifact-source descriptor remains a derived read-model or presenter contract over those existing records in 284 v1; no new descriptor columns, no second descriptor payload, and no new table or ledger are introduced
  • provider_connection_id may be persisted or derived only where current artifact truth already knows the connection; 284 does not invent a new provider-connection ownership model
  • package_run_id remains an optional nullable reference in the shared descriptor contract only; 284 does not create package-execution truth or package artifacts
• RBAC:
  • workspace membership remains the first 404 boundary
  • managed-environment entitlement remains the second 404 boundary
  • existing view capabilities for findings, evidence, reports, inventory, and tenant reviews remain authoritative
  • 284 introduces no new destructive action and no new authorization plane

Cross-Cutting / Shared Pattern Reuse

• Cross-cutting feature?: yes
• Interaction class(es): evidence/report viewers, read-only detail sections, inventory metadata, status messaging, support-diagnostic and AI source descriptors
• Systems touched: EvidenceSourceProvider, EvidenceSnapshotService, FindingsSummarySource, stored-report producers and readers, InventoryPolicyTypeMeta, TenantReviewSectionFactory, ArtifactTruthPresenter, and existing support or AI source_family consumers
• Existing pattern(s) to extend: PlatformVocabularyGlossary, GovernanceSubjectTaxonomyRegistry, CanonicalControlResolutionRequest, CanonicalControlResolver, InventoryPolicyTypeMeta, ArtifactTruthPresenter, and the existing support or AI source_family naming precedent
• Shared contract / presenter / builder / renderer to reuse: CanonicalControlResolutionRequest, CanonicalControlResolver, InventoryPolicyTypeMeta, EvidenceSnapshotService, TenantReviewSectionFactory, and ArtifactTruthPresenter
• Why the existing shared path is sufficient or insufficient: the repo already has vocabulary, control-binding, and presenter seams, but it still lacks one shared artifact-source descriptor that all artifact families can carry without page-local or service-local remapping
• Allowed deviation and why: one bounded ArtifactSourceDescriptor or equivalent normalizer or presenter seam is allowed if the current helpers cannot carry the pinned descriptor fields without duplication
• Consistency impact: findings, evidence snapshots, stored reports, inventory summaries, review sections, and touched support or AI bundles must expose the same source_family, source_kind, source_target_kind, and descriptor semantics before disclosing provider detail; control_key stays mandatory for touched findings, evidence, stored reports, and review sections, while inventory keeps the shared descriptor plus the canonical and provider type split as its primary summary
• Review focus: verify that no touched page, presenter, or service rebuilds the descriptor locally and that Microsoft-specific nouns remain nested provider detail rather than new shared platform truth

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: no
• Shared OperationRun UX contract/layer reused: N/A
• Delegated start/completion UX behaviors: N/A
• Local surface-owned behavior that remains: N/A
• Queued DB-notification policy: N/A
• Terminal notification path: N/A
• Exception required?: none

Provider Boundary / Platform Core Check

• Shared provider/platform boundary touched?: yes
• Boundary classification: mixed
• Seams affected: Finding discriminator fields, EvidenceSourceProvider result shape, EvidenceSnapshotItem persisted source metadata, StoredReport report typing, inventory metadata, canonical-control binding inputs, review-section evidence summaries, and support or AI source_family consumers if touched
• Neutral platform terms preserved or introduced: workspace_id, tenant_id, managed_environment_id, source_family, source_kind, source_target_kind, source_target_identifier, provider_key, provider_connection_id, canonical_type, detector_key, and control_key
• Provider-specific semantics retained and why: finding_type, report_type, policy_type, Microsoft object types, report domains, Graph-facing detector keys, and provider display labels remain provider-owned because the platform still needs to preserve Microsoft-native evidence and because 284 is not a fake generic rewrite of the adapters
• Why this does not deepen provider coupling accidentally: the shared descriptor moves provider detail out of the top-level artifact summary instead of expanding Microsoft-specific semantics. It adds one neutral envelope over already existing provider detail and rejects new provider registries or fake multi-provider engines.
• Follow-up path: package-execution adoption remains for later work, broader copy neutralization remains in Spec 286, and no-legacy enforcement remains in Spec 287

UI / Surface Guardrail Impact

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Findings resource summary and detail copy	yes	Native Filament + existing shared presenters	findings, evidence, review	page, detail	no	summary fields and presenter ordering only
Evidence snapshot resource summary and item detail	yes	Native Filament + shared artifact truth presenters	evidence, reports, reviews	page, detail	no	read-only evidence surface
Inventory item list and detail metadata	yes	Native Filament	inventory metadata, governed-subject labeling	page, detail	no	descriptor and type-label split only
Stored report list and detail summary	yes	Native Filament + shared artifact truth presenters	reports, evidence, support	page, detail	no	read-only reporting surface
Tenant review detail sections that summarize supporting artifacts	yes	Mixed native Filament + shared review factory	reviews, evidence, reports	detail	no	section summary and disclosure order only

Decision-First Surface Role

Surface	Decision Role	Human-in-the-loop Moment	Immediately Visible for First Decision	On-Demand Detail / Evidence	Why This Is Primary or Why Not	Workflow Alignment	Attention-load Reduction
Findings resource	Primary Decision Surface	Decide whether the finding needs follow-up now	Canonical source family, governed subject or source target, detector summary, control summary, severity, status	Provider object type, raw legacy finding type, low-level evidence payload	Primary because findings are already an operator decision queue	Follows governance-review workflow	Removes the need to decode Microsoft-only type names before triage
Evidence snapshot resource	Tertiary Evidence / Diagnostics Surface	Inspect which supporting artifacts prove the current state	Canonical source descriptor and control summary per item	Raw payloads, record ids, provider object types, legacy report or finding types	Not primary because it explains evidence after a decision surface points here	Follows evidence-inspection workflow	Keeps diagnostic depth available without making it the first summary
Inventory item resource	Secondary Context Surface	Inspect what provider object the platform currently knows about	Canonical type, provider display type, lifecycle timestamps	Raw provider object type, legacy policy_type, low-level metadata	Not primary because inventory is an inspection surface, not the first decision queue	Follows inventory-inspection workflow	Removes ambiguity between platform type and provider object type
Stored report resource	Tertiary Evidence / Diagnostics Surface	Inspect a generated provider report behind other summaries	Canonical source family, report summary, control summary when present	Provider-native report type, payload, provider detail	Not primary because reports are evidence or reporting artifacts	Follows diagnostics and reporting workflow	Keeps report meaning readable without turning report_type into platform truth
Tenant review detail sections	Secondary Context Surface	Cross-check which supporting artifacts justify the review state	Canonical source summary and control summary	Raw artifact payloads and provider-native identifiers	Not primary because the review decision already exists at the review level	Follows review workflow	Prevents section summaries from restating provider-native detail as the main conclusion

Audience-Aware Disclosure

Surface	Audience Modes In Scope	Decision-First Default-Visible Content	Operator Diagnostics	Support / Raw Evidence	One Dominant Next Action	Hidden / Gated By Default	Duplicate-Truth Prevention
Findings resource	operator-MSP, support-platform	canonical source family, governed subject, detector summary, control summary, severity, status	provider display type, legacy finding type, related operation or review links	raw payloads and provider-native evidence	Open finding detail or the existing remediation path	raw payload excerpts remain collapsed or lower on the page	finding summary states artifact meaning once; detail adds proof rather than a second competing label
Evidence snapshot resource	operator-MSP, support-platform	source descriptor per snapshot item, completeness state, control summary	provider object type, source record references, freshness detail	raw evidence payloads	Inspect evidence item	payload detail remains secondary	canonical item summary stays aligned with findings and review sections
Inventory item resource	operator-MSP, support-platform	canonical type and provider display type	provider object type, source timestamps, sync provenance	raw metadata	Open inventory item	raw meta_jsonb remains diagnostics-only	canonical type is shown once and not duplicated as a second headline
Stored report resource	operator-MSP, support-platform	source family, report headline, latest freshness	provider-native report type, detector detail, fingerprints	raw payload	Open report detail	raw JSON remains hidden or lower priority	report summary uses canonical source family once and nests provider detail
Tenant review detail sections	operator-MSP, support-platform	artifact source summary and control summary inside each section	provider object type, legacy type names, supporting links	raw evidence bundles and payloads	Inspect related artifact	raw provider detail remains gated to deeper disclosure	section summary stays aligned with the owning review summary instead of restating a second truth

UI/UX Surface Classification

Surface	Action Surface Class	Surface Type	Likely Next Operator Action	Primary Inspect/Open Model	Row Click	Secondary Actions Placement	Destructive Actions Placement	Canonical Collection Route	Canonical Detail Route	Scope Signals	Canonical Noun	Critical Truth Visible by Default	Exception Type / Justification
Findings resource	Monitoring / Queue / Workbench	Queue / Review Surface	Open the finding and decide follow-up	Full-row open to detail	required	Existing contextual actions stay in row More or detail header	existing destructive-like mutations remain grouped and confirmation-protected	workspace-first findings list	workspace-first finding detail	workspace, managed environment, severity, status	Finding	canonical source family, governed subject, and control summary	none
Evidence snapshot resource	List / Table / Bulk	Read-only Registry / Report Surface	Open the snapshot item that proves a state	Existing list or detail page	required	Existing safe links remain contextual	none	workspace-first evidence list	workspace-first evidence detail	workspace, managed environment, completeness state	Evidence snapshot	source descriptor and control summary	none
Inventory item resource	List / Table / Bulk	Read-only Registry / Report Surface	Open the provider object behind the canonical type	Full-row open to detail	required	Existing safe links remain contextual	none	workspace-first inventory item list	workspace-first inventory item detail	workspace, managed environment, canonical type	Inventory item	canonical type and provider display type	none
Stored report resource	List / Table / Bulk	Read-only Registry / Report Surface	Open the report that explains the current posture	Full-row open to detail	required	Existing safe links remain contextual	none	workspace-first stored-report list	workspace-first stored-report detail	workspace, managed environment, freshness	Stored report	source family and report summary	none
Tenant review detail sections	Record / Detail / Edit	Detail-first Operational Surface	Open the related artifact or supporting evidence	Existing review detail section links	n/a	Contextual related links only	none	workspace-first tenant-review list	workspace-first tenant-review detail	workspace, managed environment, review status	Review section evidence	canonical artifact source and control summary	none

Operator Surface Contract

Surface	Primary Persona	Decision / Operator Action Supported	Surface Type	Primary Operator Question	Default-visible Information	Diagnostics-only Information	Status Dimensions Used	Mutation Scope	Primary Actions	Dangerous Actions
Findings resource	Tenant operator	Decide whether the finding needs action	Queue / Review Surface	What artifact triggered this finding and what control does it affect?	source family, governed subject, detector summary, control summary, severity, status	raw payloads, provider-native ids, legacy type names	lifecycle, severity, governance state	existing finding workflow only	existing inspect and remediation actions	existing closure or governance actions only
Evidence snapshot resource	Tenant operator	Inspect which artifacts prove the current evidence state	Read-only Registry / Report Surface	Which artifact family produced this evidence and what control does it support?	source descriptor, control summary, freshness, completeness	raw payloads, source record references	evidence completeness, freshness	read-only	existing inspect links	none
Inventory item resource	Tenant operator	Inspect inventory classification and provider provenance	Read-only Registry / Report Surface	What canonical thing is this item, and what provider object produced it?	canonical type, provider display type, platform, timestamps	raw provider object type, legacy metadata	freshness, sync recency	read-only	existing inspect links	none
Stored report resource	Tenant operator	Inspect a report backing another summary	Read-only Registry / Report Surface	What report family is this and what artifact lineage does it represent?	source family, freshness, summary headline	raw payload, fingerprints, provider report type	freshness, availability	read-only	existing inspect links	none
Tenant review detail sections	Tenant operator	Inspect supporting artifact context behind the review	Detail-first Operational Surface	Which artifact family and control summary justify this review section?	canonical artifact summary and control summary	raw evidence bundles, provider-native ids	review lifecycle, evidence completeness	existing review workflow only	existing inspect links	none

Proportionality Review

• New source of truth?: no new persisted source of truth; one derived shared contract over existing artifact truth
• New persisted entity/table/artifact?: no
• New abstraction?: yes
• New enum/state/reason family?: yes
• New cross-domain UI framework/taxonomy?: yes, but only as a bounded artifact-source and inventory-type taxonomy tied to current-release artifact seams
• Current operator problem: the same artifact lineage is currently described with Microsoft-specific nouns in one surface and platform-adjacent summaries in another, which makes evidence, reports, findings, inventory, and reviews harder to interpret safely
• Existing structure is insufficient because: current helpers already normalize vocabulary, control bindings, or display order in isolation, but no shared contract pins what an artifact source is across findings, evidence, reports, and inventory metadata
• Narrowest correct implementation: add one descriptor contract, one inventory type split, and the smallest normalizer or presenter seam necessary to derive them from existing records, current payloads, and presenters
• Ownership cost: additive migrations or payload shape updates, translator or presenter upkeep, legacy-row interpretation rules, and focused proof for both read models and touched Filament surfaces
• Alternative intentionally rejected: page-local aliasing or report-local mapping was rejected because it would keep artifact meaning inconsistent; a larger detector catalog or provider framework was rejected because it is future-facing and not required for current repo truth
• Release truth: current-release provider-neutral artifact interpretation over existing Microsoft-first artifacts, not a speculative package engine or cross-provider platform rewrite

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by this spec.

Canonical replacement is preferred over preservation, except where existing Microsoft-produced artifacts must remain readable as provider-owned historical detail.

Testing / Lane / Runtime Impact

• Test purpose / classification: Unit, Feature, Browser
• Validation lane(s): fast-feedback, confidence, browser
• Why this classification and these lanes are sufficient: the pinned taxonomy inventory and descriptor normalizer are pure derivation and need unit proof; findings, evidence snapshots, stored reports, inventory metadata, and touched presenters need feature proof; one browser smoke is enough to prove the operator sees the new descriptor-first disclosure under the live Filament shell
• New or expanded test families: focused artifact-source unit tests, artifact-contract feature tests, one guard test, and one browser smoke
• Fixture / helper cost impact: moderate because proof needs workspace, managed environment, findings, reports, evidence snapshots, and inventory fixtures without widening shared defaults
• Heavy-family visibility / justification: none beyond one narrow browser smoke for touched operator-facing read paths
• Special surface test profile: standard-native-filament, shared-detail-family
• Standard-native relief or required special coverage: most surfaces need ordinary feature coverage; the read-only review section and evidence summary contract need shared-detail-family assertions to keep disclosure ordering stable
• Reviewer handoff: verify the exact pinned inventories across artifacts, confirm touched surfaces show canonical descriptor first and provider detail second, confirm no new table or backfill appears, and rely on the proof commands below rather than broad suite guesses
• Budget / baseline / trend impact: contained feature-local increase only
• Escalation needed: reject-or-split if implementation adds a detector catalog, package runtime, provider framework, historical backfill, or adjacent copy or RBAC scope
• Active feature PR close-out entry: Guardrail
• Planned validation 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)

User Scenarios & Testing

User Story 1 - Interpret findings, evidence, and reports with one source descriptor (Priority: P1)

As an operator, I want findings, evidence snapshots, and stored reports to expose the same artifact source summary so I can understand what produced the current signal without decoding Microsoft-only type names first.

Why this priority: this is the core reason for 284. If findings, evidence, and reports still describe the same lineage differently, the taxonomy does not solve the real product problem.

Independent Test: create or load one finding, one evidence snapshot, and one stored report for the same managed environment and confirm they each expose the canonical source family, target, detector summary, and control summary before any provider-native detail.

Acceptance Scenarios:

1. Given a drift finding still carries policy_type in evidence_jsonb, When the operator opens the finding or evidence summary, Then the surface shows the canonical source descriptor first and keeps the Microsoft policy type as provider detail.
2. Given a stored permission-posture or Entra-admin-roles report exists, When the operator opens the report, Then the surface shows the shared source family and report meaning first and nests the raw report_type and provider payload below that summary.

---

User Story 2 - Read inventory items without treating policy_type as universal platform truth (Priority: P1)

As an operator, I want inventory items to distinguish the platform's canonical type from the provider's object type and display type so I can inspect inventory without assuming Microsoft naming is the only valid domain model.

Why this priority: the candidate explicitly calls out inventory metadata. If inventory keeps using policy_type as top-level truth, later package-output and reporting work will keep inheriting that false universal.

Independent Test: open one inventory item with an existing Microsoft-backed policy type and confirm the page exposes canonical_type, provider_object_type, and provider_display_type as separate concepts.

Acceptance Scenarios:

1. Given an inventory item was captured from a Microsoft object type such as deviceCompliancePolicy, When the operator opens the item, Then the page shows the canonical platform type separately from the raw provider object type.
2. Given the inventory item has a user-facing label, When the operator scans the list or detail view, Then the provider display type is readable without replacing the canonical type as the platform's primary metadata.

---

User Story 3 - Keep evidence, reviews, and reporting surfaces descriptor-first (Priority: P2)

As an operator, I want evidence, review, and reporting surfaces to disclose canonical artifact source summaries first and provider detail second so review decisions stay readable and diagnostic depth remains available.

Why this priority: changing the underlying model without changing the first-decision summary would still leave the UI teaching the old artifact truth.

Independent Test: open the evidence snapshot resource, a tenant review with supporting sections, and a stored report, then confirm each touched summary leads with the same canonical descriptor fields and keeps raw provider detail in secondary disclosure.

Acceptance Scenarios:

1. Given a tenant review section summarizes evidence from findings and reports, When the operator opens the review detail, Then the section shows the same source family and control summary used by the underlying artifacts instead of inventing a third summary label.
2. Given an evidence snapshot item or stored report has raw provider payload available, When the operator opens the detail page, Then canonical descriptor fields stay in the summary region and raw provider payload remains diagnostics-only.

---

User Story 4 - Reuse source-family semantics in downstream shared consumers without adding package runtime (Priority: P3)

As a maintainer, I want touched support or AI source-family consumers and future package-output work to reuse the same source-family semantics so later packaging or summarization features do not need a second artifact taxonomy.

Why this priority: later package-output work is explicitly an acceptance target for 284, but 284 itself must stop before inventing package runtime.

Independent Test: inspect the shared descriptor contract, touched support or AI source-family consumers, and the logical contract package slot, then confirm they use the same source-family nouns and leave package_run_id optional and unused in the current release.

Acceptance Scenarios:

1. Given a touched support or AI summary declares a source_family, When it references artifact-source semantics after 284, Then it uses the same source-family vocabulary as the new artifact descriptor.
2. Given the ArtifactSourceDescriptor includes optional package_run_id, When current-release artifacts are rendered, Then the field stays null or absent and does not imply that package runtime already exists.

Edge Cases

• A historical finding has source = null and only finding_type plus evidence_jsonb from an older write path.
• A drift finding still carries only Microsoft policy_type or raw detector detail, but the canonical type mapping is missing or incomplete.
• A stored report already has provider_key = microsoft in payload while report_type remains a Microsoft-shaped top-level discriminator.
• An evidence source summary aggregates many records and therefore has no single source_record_id, so the shared descriptor must still point to the right source_target_kind and optional identifier.
• An inventory item has no friendly provider display label, so the canonical type and provider object type must still remain distinct without inventing fake display copy.
• provider_connection_id is not available for a historical artifact even though the provider key and managed environment are known.
• A touched support or AI consumer already uses source_family semantics that would conflict with the new artifact family names if left unchanged.

Requirements

Constitution alignment (required): This slice changes artifact typing, artifact-source derivation, read-only summary disclosure, and canonical-control binding inputs across findings, evidence, stored reports, inventory, and review summaries. It does not introduce a new Graph contract path, a new long-running workflow, or a new persisted artifact ledger.

Constitution alignment (PROP-001 / ABSTR-001 / PROV-001 / BLOAT-001): One shared descriptor and one inventory type split are justified because the repo already has multiple live artifact families and conflicting interpretations of the same Microsoft-produced truth. No provider framework, no detector registry, no control-catalog expansion, and no new table are in scope.

Constitution alignment (XCUT-001 / UI-FIL-001 / DECIDE-001): The feature must reuse the existing findings, evidence, stored-report, inventory, and tenant-review surfaces. It may refine their summary ordering and view models, but it must not create a new dashboard, a second evidence viewer, or local semantic color or status systems.

Constitution alignment (RBAC-UX): Workspace and managed-environment boundaries remain unchanged. Existing view capabilities remain authoritative, and provider-neutral artifact typing must not widen who can see findings, evidence, reports, inventory, or reviews.

Constitution alignment (TEST-GOV-001): Proof stays bounded to focused unit, feature, guard, and one narrow browser smoke. The descriptor inventory, descriptor fields, and proof commands must stay pinned identically across the package.

Functional Requirements

• FR-001: The system MUST introduce one shared artifact-source descriptor for findings, evidence snapshots, stored reports, inventory metadata, and touched review or summary consumers.
• FR-002: The shared artifact-source descriptor MUST standardize these fields: workspace_id, tenant_id, managed_environment_id, source_family, source_kind, provider_key, provider_connection_id, source_target_kind, source_target_identifier, detector_key, control_key, and optional package_run_id.
• FR-003: The initial source_family inventory for 284 v1 MUST be exactly finding, stored_report, evidence_snapshot, inventory, and operation_run.
• FR-004: The initial source_kind inventory for 284 v1 MUST be exactly model_summary, stored_report, operation_rollup, and inventory_projection.
• FR-005: The initial source_target_kind inventory for 284 v1 MUST be exactly managed_environment, governed_subject, provider_connection, and operation_run.
• FR-006: 284 v1 MUST NOT introduce a global detector catalog or a broader control-catalog expansion; detector_key remains a standardized field and naming rule, not a new registry of every detector in the platform.
• FR-007: Findings MUST derive the shared descriptor from existing finding_type, source, and evidence_jsonb fields without requiring historical backfill.
• FR-008: EvidenceSourceProvider and EvidenceSnapshotService MUST carry or derive the shared descriptor consistently so EvidenceSnapshotItem does not rely on source_record_type alone as its top-level artifact identity.
• FR-009: Stored reports MUST align report_type with shared source-family semantics while keeping report_type itself as provider-owned detail where needed.
• FR-010: Inventory metadata MUST expose canonical_type, provider_object_type, and provider_display_type as separate concepts and MUST stop treating raw policy_type as the only platform-wide artifact type.
• FR-011: Touched canonical-control consumers MUST resolve or disclose control_key through the shared descriptor path instead of rebuilding platform truth from page-local Microsoft type checks.
• FR-012: Touched findings, evidence, stored-report, and tenant-review presenters MUST show canonical descriptor fields and control_key before provider-native detail. Inventory presenters MUST show the shared source descriptor and the canonical/provider type split before raw provider metadata.
• FR-013: Existing Microsoft artifacts MUST remain valid and interpretable as provider_key = microsoft sources after 284 lands.
• FR-014: 284 MUST NOT require historical backfill; legacy rows may be normalized on read or through additive future writes only.
• FR-015: package_run_id MAY exist as a nullable field in the shared descriptor contract, but 284 MUST NOT create package runtime, package-run persistence, or package-output surfaces.
• FR-016: Touched support or AI source-family consumers MUST use the same source-family nouns as the shared descriptor if they are updated in this slice.
• FR-017: The implementation MUST NOT introduce a new artifact table, provider framework, compliance engine, detector registry, full control-catalog expansion, RBAC rewrite, copy-neutralization pass, or no-legacy enforcement pack.
• FR-018: The descriptor inventory and source-type split MUST stay pinned identically across spec.md, plan.md, research.md, data-model.md, quickstart.md, tasks.md, the logical contract, and the readiness checklist. The canonical proof commands MUST stay pinned identically across spec.md, plan.md, quickstart.md, tasks.md, and the readiness checklist.
• FR-019: Before runtime implementation begins, SCOPE-001 ownership compliance for touched tenant-owned artifact tables MUST be satisfied or explicitly excepted; 284 MUST NOT silently waive that prerequisite.

Authorization and Safety Requirements

• AR-001: Workspace membership MUST remain the first access boundary for touched findings, evidence, reports, inventory, and review surfaces.
• AR-002: Managed-environment entitlement MUST remain the second access boundary for those surfaces.
• AR-003: Non-members or cross-workspace or cross-environment access attempts MUST continue to resolve as 404, while in-scope actors missing resource capabilities still resolve as 403.
• AR-004: 284 introduces no new destructive action. Any touched destructive or high-impact action on findings or adjacent resources MUST remain confirmation-protected and server-authorized under the current action contract.
• AR-005: Navigation-only related links on touched read-only artifact surfaces MUST remain clearly navigation-only and must not be re-expressed as mutations during this slice.
• AR-006: Provider-neutral artifact typing MUST NOT bypass or weaken the current resource policies and capability checks.

Non-Functional Requirements

• NFR-001: Filament remains v5 on Livewire v4.
• NFR-002: Provider registration remains in apps/platform/bootstrap/providers.php; nothing moves to bootstrap/app.php.
• NFR-003: Asset strategy remains unchanged. No new panel or shared asset registration is expected from 284.
• NFR-004: FindingResource and InventoryItemResource keep valid View pages for any existing or future global-search posture. EvidenceSnapshotResource, StoredReportResource, and TenantReviewResource remain non-globally-searchable while keeping View pages.
• NFR-005: The feature must remain reviewable as one bounded artifact-source slice and MUST NOT silently absorb work reserved for Specs 285 through 287.
• NFR-006: Default-visible summary fields on touched operator-facing surfaces must stay Filament-native and avoid page-local card, badge, or semantic color systems.

UI Action Matrix

Surface	Location	Header Actions	Inspect Affordance (List or Table)	Row Actions (max 2 visible)	Bulk Actions (grouped)	Empty-State CTA(s)	View Header Actions	Create or Edit Save+Cancel	Audit log?	Notes / Exemptions
Findings resource	FindingResource	preserve existing header actions	clickable row to View	preserve existing contextual actions and grouping	preserve existing grouped bulk actions only	preserve current empty-state behavior	preserve existing detail-header actions	preserve existing edit or workflow forms where applicable	preserve current mutation audit behavior	284 changes descriptor and summary semantics only
Evidence snapshot resource	EvidenceSnapshotResource	preserve existing read-only actions	clickable row to View	preserve current safe related links only	none	preserve current empty-state behavior	preserve existing read-only header actions	N/A	no new audit surface	descriptor-first disclosure only
Inventory item resource	InventoryItemResource	preserve current no-header-action posture	clickable row to View	preserve current row behavior	none	preserve current no-CTA posture	preserve existing read-only detail actions	N/A	no new audit surface	inventory type split only
Stored report resource	StoredReportResource	preserve existing read-only actions	clickable row to View	preserve current safe actions only	none	preserve current empty-state behavior	preserve existing read-only header actions	N/A	no new audit surface	source-family and summary semantics only
Tenant review detail sections	TenantReviewResource and TenantReviewSectionFactory	preserve existing header and section actions	existing section links remain inspect affordances	preserve current safe contextual links	none	N/A	preserve existing review-header actions	preserve current review flows	preserve current review audit behavior	section summary ordering only

All other touched support or AI consumers must keep their existing action contracts and only adopt the shared source-family vocabulary where 284 touches them.

Key Entities

• Artifact Source Descriptor: one shared contract describing source family, source kind, provider, source target, optional target identifier, detector key, control key, and optional package-run reference for an artifact or summary.
• Inventory Type Descriptor: the bounded inventory metadata split separating canonical_type, provider_object_type, and provider_display_type while preserving legacy policy_type as provider-owned detail.
• Artifact Provider Detail: provider-owned raw fields such as finding_type, report_type, provider object type, Graph-facing detector detail, or legacy policy_type retained as nested evidence rather than top-level platform truth.
• Artifact Source View Model: the derived presenter contract used by findings, evidence, reports, inventory, and tenant-review sections to disclose canonical descriptor fields first and provider detail second.

Success Criteria

Measurable Outcomes

• SC-001: 100% of touched findings, evidence snapshots, stored reports, inventory items, and tenant-review artifact summaries expose the shared source descriptor before provider-native detail.
• SC-002: 100% of touched inventory item summaries expose canonical_type, provider_object_type, and provider_display_type as separate fields.
• SC-003: 100% of touched artifact summaries that already resolve a canonical control continue to expose control_key consistently through the shared descriptor path.
• SC-004: The implementation introduces no new artifact table, no historical backfill requirement, and no package runtime while keeping existing Microsoft-produced artifacts readable as Microsoft provider sources.