Main Confidence / confidence (push) Waiting to run

Details

feat: neutralize provider connection target-scope surfaces (#274 )

## Summary
- add a shared provider target-scope descriptor, normalizer, identity-context metadata, and surface-summary layer
- update provider connection list, detail, create, edit, and onboarding surfaces to use neutral target-scope vocabulary while keeping Microsoft identity contextual
- align provider connection audit and resolver output with the neutral target-scope contract and add focused guard/unit/feature coverage for regressions

## Validation
- browser smoke: opened the tenant-scoped provider connection list, drilled into detail, and verified the edit/create surfaces in local admin context

## Notes
- this PR comes from the session branch created for the active feature work
- no additional runtime or persistence layer was introduced in this slice

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #274

2026-04-25 09:07:40 +00:00

6.7 KiB

Raw Blame History

Data Model: Provider Identity & Target Scope Neutrality

Overview

This slice introduces one shared target-scope descriptor, one provider-owned contextual identity metadata shape, one operator-facing connection summary, and one narrow neutrality guard result. No new database persistence is introduced.

Entity: ProviderConnectionTargetScopeDescriptor

Purpose: Express the neutral platform meaning of what a provider connection points to without carrying provider-specific identity as part of the descriptor itself.
Identity:
- provider_connection_id for existing records
- draft or create-flow input tuple (provider, scope_kind, scope_identifier, scope_display_name) before persistence
Core fields:
- provider
- scope_kind
- scope_identifier
- scope_display_name
- shared_label
- shared_help_text
Validation rules:
- The descriptor must remain renderable without provider-specific labels.
- In this current-release slice, scope_kind is tenant-only even though the neutral field remains generic for future provider-boundary-safe extension.
- scope_kind, scope_identifier, and scope_display_name must be sufficient to describe the neutral target-scope meaning on shared surfaces.
- scope_identifier and scope_display_name must be usable on shared surfaces without relying on Microsoft directory vocabulary.
- Provider-owned identity details must live beside the descriptor in contextual metadata or summary shapes, not inside the descriptor itself.

Entity: ProviderConnectionTargetScopeNormalizationResult

Purpose: Represent the deterministic result of normalizing create or edit input before persistence, including explicit blocked outcomes for unsupported combinations or missing provider context.
Fields:
- status
- provider
- scope_kind
- target_scope when status = normalized
- contextual_identity_details[] when status = normalized
- preview_summary when a shared-surface preview can be derived without assuming persisted runtime state
- failure_code
- message
Status values:
- normalized
- blocked
Failure code values:
- none
- unsupported_provider_scope_combination
- missing_provider_context
Validation rules:
- normalized results must carry provider, scope_kind, target_scope, contextual_identity_details[], failure_code = none, and a human-readable message; they may include preview_summary only when consent and verification state can be derived without assuming persisted runtime state.
- blocked results must carry provider, scope_kind, failure_code, and message and must not pretend readiness or persisted summary truth exists.
- The normalization result must preserve the distinction between neutral target-scope truth and provider-owned contextual identity details.

Entity: ProviderIdentityContextMetadata

Purpose: Carry provider-owned identity details that remain necessary for Microsoft consent, verification, troubleshooting, or audit drill-in.
Fields:
- provider
- detail_key
- detail_label
- detail_value
- visibility
Visibility values:
- contextual_only
- audit_only
- troubleshooting_only
Validation rules:
- Context metadata must never replace the shared target-scope descriptor on generic provider surfaces.
- Microsoft-only labels such as Entra tenant ID remain allowed only when provider = microsoft and visibility is contextual.

Entity: ProviderConnectionSurfaceSummary

Purpose: Define the default-visible operator-facing summary for shared provider connection surfaces.
Fields:
- provider
- target_scope
- consent_state
- verification_state
- readiness_summary
- contextual_identity_details[]
Validation rules:
- provider, target_scope, consent_state, and verification_state must all be visible without opening diagnostics.
- contextual_identity_details[] must remain secondary to the target-scope summary.
- Shared surface summaries must not collapse consent and verification into one ambiguous state.

Entity: ProviderConnectionNeutralityCheckResult

Purpose: Deterministic result shape used by guard tests and review checks.
Fields:
- status
- surface_key
- path
- surface_ownership
- allowed_exception_classes[]
- violation_code
- message
- suggested_follow_up
Status values:
- allowed
- review_required
- blocked
Violation code examples:
- provider_specific_default_label
- provider_specific_default_filter
- provider_specific_required_field
- provider_specific_validation_message
- provider_specific_default_helper_copy
- provider_specific_default_audit_prose
- missing_target_scope_descriptor
Surface ownership values:
- platform_core
- provider_owned
Validation rules:
- allowed means the shared surface uses neutral target-scope truth by default.
- review_required means the path contains documented provider-owned contextual detail or an allowed exception class.
- blocked means a shared surface reintroduced provider-specific default truth.

Relationships

One ProviderConnectionSurfaceSummary consumes exactly one ProviderConnectionTargetScopeDescriptor and may carry zero or more ProviderIdentityContextMetadata entries beside it.
One ProviderConnectionTargetScopeNormalizationResult may carry zero or more ProviderIdentityContextMetadata entries beside exactly one normalized target-scope descriptor.
One ProviderConnectionNeutralityCheckResult references exactly one touched surface or helper path.

Lifecycle

Target-scope descriptor lifecycle

draft_input: create or edit flow has neutral shared scope data but is not yet persisted.
persisted_shared_truth: existing provider_connections row has a neutral target-scope descriptor available for shared surfaces.
context_enriched: provider-owned contextual details are attached for Microsoft consent, verification, or audit drill-in.

Neutrality check lifecycle

allowed: shared surface is neutral by default.
review_required: shared surface stays neutral but exposes documented provider-owned contextual detail.
blocked: shared surface or helper reintroduced provider-specific default truth.

Rollout Model

No new database table or column is planned for this slice.
The descriptor layer is derived from existing provider connection truth and existing provider-owned identity details.
Provider connection list, detail, create, edit, onboarding provider setup, and audit wording adopt the new descriptor first.
Broader provider identity migration and compare-boundary work remain out of scope for this feature.

6.7 KiB Raw Blame History