TenantAtlas/specs/104-provider-permission-posture/research.md

# Research: Provider Permission Posture (Spec 104)

**Date**: 2026-02-21 | **Branch**: `104-provider-permission-posture`

## R1 — Posture Job Trigger Mechanism

**Decision**: Event-driven dispatch after `TenantPermissionService::compare()` completes.

**Rationale**: The `ProviderConnectionHealthCheckJob` already calls `compare()` at L116–L131 and has the full `$permissionComparison` result array. Dispatching `GeneratePermissionPostureFindingsJob` immediately after `compare()` within the health check job:
- Guarantees posture data freshness (always in sync with latest permission state)
- Requires no new scheduling infrastructure
- Follows the project's existing pattern of chaining work within health check jobs

**Alternatives considered**:
- Independent schedule: Rejected because posture data would lag permission checks
- Manual trigger: Rejected because it defeats the automation goal
- Laravel model events on TenantPermission: Rejected because `compare()` batch-upserts multiple records — a model event per-permission creates N dispatches instead of 1

**Hook point**: `ProviderConnectionHealthCheckJob::handle()`, after `compare()` returns at ~L131, before `TenantPermissionCheckClusters::buildChecks()`.

## R2 — Finding `resolved` Status (Global Scope)

**Decision**: `resolved` is a global Finding status, available for all finding types.

**Rationale**: The `findings.status` column is a generic string — no enum constraint. Adding `STATUS_RESOLVED = 'resolved'` to the Finding model and the `FindingStatusBadge` mapper makes the lifecycle universal. This avoids fragmenting status semantics per finding type.

**Migration requirements**:
- Add `resolved_at` (timestampTz, nullable) to `findings` table
- Add `resolved_reason` (string, nullable) to `findings` table
- Add `STATUS_RESOLVED = 'resolved'` constant to `Finding` model
- Add resolved badge mapping to `FindingStatusBadge`
- No index needed on `resolved_at` (queries filter by `status` which is already indexed)

**Alternatives considered**:
- Scoped to permission_posture only: Rejected because it fragments the status model unnecessarily
- Separate resolved_findings table: Rejected (over-engineering for a status change)

## R3 — Finding Re-open Behavior

**Decision**: Re-open existing finding by resetting status to `new` and clearing `resolved_at`/`resolved_reason`.

**Rationale**: The `[tenant_id, fingerprint]` unique constraint means only one finding per permission per tenant can exist. Re-opening preserves the original `created_at` and audit trail. The `DriftFindingGenerator` pattern at L95–L142 also uses `firstOrNew` and updates in-place.

**Implementation**: When `firstOrNew` finds a resolved finding, set `status = new`, `resolved_at = null`, `resolved_reason = null`, update `evidence_jsonb` with current state.

## R4 — Auto-resolve Scope (all statuses)

**Decision**: Auto-resolve applies to both `new` and `acknowledged` findings.

**Rationale**: A finding represents a factual state ("permission X is missing"). When the fact changes, the finding should be resolved regardless of human acknowledgement. Acknowledgement metadata (`acknowledged_at`, `acknowledged_by`) is preserved for audit — only `status`, `resolved_at`, `resolved_reason` change.

## R5 — StoredReport Table Design

**Decision**: New generic `stored_reports` table following constitution SCOPE-001 ownership rules.

**Rationale**: The constitution explicitly lists `StoredReports/Exports` as tenant-owned. The table must include `workspace_id` (NOT NULL) and `tenant_id` (NOT NULL) per SCOPE-001 database convention for tenant-owned tables. A polymorphic `report_type` string enables reuse by future domains without schema changes.

**Schema decision**: JSONB `payload` column with GIN index for future querying. No separate columns for individual payload fields — the payload structure is type-dependent.

## R6 — Alert Integration Pattern

**Decision**: Add `EVENT_PERMISSION_MISSING` constant to `AlertRule` and a `permissionPostureEvents()` method to `EvaluateAlertsJob`.

**Rationale**: The existing alert pipeline follows a clear pattern:
1. `EvaluateAlertsJob::handle()` collects events from dedicated methods
2. Each method queries recent data within a time window
3. Events are dispatched to `AlertDispatchService::dispatchEvent()`
4. No structural changes needed — just a new event type + query method

**Implementation**:
- `AlertRule::EVENT_PERMISSION_MISSING = 'permission_missing'`
- New method `EvaluateAlertsJob::permissionMissingEvents()` queries open `permission_posture` findings with severity >= minimum
- Event fingerprint: `permission_missing:{tenant_id}:{permission_key}` for cooldown dedup

## R7 — Operation Run Integration

**Decision**: Track posture generation as `OperationRun` with `type = 'permission_posture_check'`.

**Rationale**: Constitution requires OperationRun for queued jobs. `OperationCatalog` already has ~20 type constants. Adding one more follows the existing pattern.

**Implementation**: Add `TYPE_PERMISSION_POSTURE_CHECK = 'permission_posture_check'` to `OperationCatalog`. The job creates/starts the run, processes all permissions for a tenant, records counts, and completes.

## R8 — Severity Derivation from Feature Impact

**Decision**: Use the `features` array from `config/intune_permissions.php` to determine severity.

**Rationale**: Each permission entry has a `features` array listing which product features depend on it. Counting blocked features maps directly to severity tiers defined in FR-005.

**Implementation**: `count($permission['features'])` → 0=low, 1=medium, 2=high, 3+=critical. This is deterministic and changes automatically when the registry is updated.

## R9 — Retention Mechanism for StoredReports

**Decision**: Scheduled artisan command that prunes reports older than configurable threshold.

**Rationale**: Standard Laravel pattern for data lifecycle management. A simple query `StoredReport::where('created_at', '<', now()->subDays($days))->delete()` in a scheduled command. Default: 90 days via `config/tenantpilot.php`.

**Alternatives considered**:
- Database TTL/partitioning: Over-engineering for the expected volume
- Soft delete: Unnecessary — reports are immutable snapshots, not user-managed records