# Feature Specification: Drift MVP

**Feature Branch**: `feat/044-drift-mvp`  
**Created**: 2026-01-07  
**Status**: Draft  

## Purpose

Detect and report drift between expected and observed states using inventory and run metadata.

This MVP focuses on reporting and triage, not automatic remediation.

## Clarifications

### Session 2026-01-12

- Q: How should Drift pick the baseline run for a given tenant + scope? → A: Baseline = previous successful inventory run for the same scope; compare against the latest successful run.
- Q: Should Drift findings be persisted or computed on demand? → A: Persist findings in DB per comparison (baseline_run_id + current_run_id), including a deterministic fingerprint for stable identity + triage.
- Q: How define the fingerprint (Stable ID) for a drift finding? → A: `sha256(tenant_id + scope_key + subject_type + subject_external_id + change_type + baseline_hash + current_hash)` (normalized; excludes volatile fields).
- Q: Which inventory entities/types are in scope for Drift MVP? → A: Policies + Assignments.
- Q: When should drift findings be generated? → A: On-demand when opening Drift: if findings for (baseline,current,scope) don’t exist yet, dispatch an async job to generate them.

## Pinned Decisions (MVP defaults)

- Drift is implemented as a generator that writes persisted Finding rows (not only an in-memory/on-demand diff).
- Baseline selection: baseline = previous successful inventory run for the same scope_key; comparison = latest successful inventory run for the same scope_key.
- Scope is first-class via `scope_key` and must be deterministic to support future pinned baselines and compare workflows.
- Fingerprints are deterministic and stable for triage/audit workflows.
- Drift MVP only uses `finding_type=drift` and `status` in {`new`, `acknowledged`}.
- Default severity: `medium` (until a rule engine exists).
- UI must not perform render-time Graph calls. Graph access (if any) is limited to background sync/jobs.

## Key Entities / Generic Findings (Future-proof)

### Finding (generic)

We want Drift MVP to remain MVP-sized, while making it easy to add future generators (Security Suite Audits, Cross-tenant Compare) without inventing a new model.

Rationale:
- Drift = delta engine over runs.
- Audit = rule engine over inventory.
- Both write Findings with the same semantics: deterministic fingerprint + triage + minimized evidence.

- `finding_type` (enum): `drift` (MVP), later `audit`, `compare`
- `tenant_id`
- `scope_key` (string): deterministic scope identifier (see Scope Definition / FR1)
- `baseline_run_id` (nullable; e.g. audit/compare)
- `current_run_id` (nullable; e.g. audit)
- `fingerprint` (string): deterministic; unique per tenant+scope+subject+change
- `subject_type` (string): e.g. policy type (or other inventory entity type)
- `subject_external_id` (string): Graph external id
- `severity` (enum): `low` / `medium` / `high` (MVP default: `medium`)
- `status` (enum): `new` / `acknowledged` (later: `snoozed` / `assigned` / `commented`)
- `acknowledged_at` (nullable)
- `acknowledged_by_user_id` (nullable)
- `evidence_jsonb` (jsonb): sanitized, small, secrets-free (no raw payload dumps)
- Optional/nullable for later (prepared; out of MVP): `rule_id`, `control_id`, `expected_value`, `source`

MVP implementation scope: only `finding_type=drift`, statuses `new/acknowledged`, and no rule engine.

## User Scenarios & Testing

### Scenario 1: View drift summary
- Given inventory sync has run at least twice
- When the admin opens Drift
- Then they see a summary of changes since the last baseline

### Scenario 2: Drill into a drift finding
- Given a drift finding exists
- When the admin opens the finding
- Then they see what changed, when, and which run observed it

### Scenario 3: Acknowledge/triage
- Given a drift finding exists
- When the admin marks it acknowledged
- Then it is hidden from “new” lists but remains auditable

## Functional Requirements

- FR1: Baseline + scope
	- Define `scope_key` as a deterministic string derived from the Inventory Selection.
		- Example: `scope_key = sha256(normalized selection payload)`.
		- Must remain stable across equivalent selections (normalization), and allow future pinned baselines / compare baselines.
	- Baseline run (MVP) = previous successful inventory run for the same `scope_key`.
	- Comparison run (MVP) = latest successful inventory run for the same `scope_key`.

- FR2: Finding generation (Drift MVP)
	- Findings are persisted per (`baseline_run_id`, `current_run_id`, `scope_key`).
	- Findings cover adds, removals, and metadata changes for supported entities (Policies + Assignments).
	- Findings are deterministic: same baseline/current + scope_key ⇒ same set of fingerprints.

- FR2a: Fingerprint definition (MVP)
	- Fingerprint = `sha256(tenant_id + scope_key + subject_type + subject_external_id + change_type + baseline_hash + current_hash)`.
	- `baseline_hash` / `current_hash` are hashes over normalized, sanitized comparison data (exclude volatile fields like timestamps).
	- Goal: stable identity for triage + audit compatibility.

- FR2b: Drift MVP scope includes Policies and their Assignments.
	- Assignment drift includes target changes (e.g., groupId) and intent changes.

- FR3: Provide Drift UI with summary and details.

- FR4: Triage (MVP)
	- Admin can acknowledge a finding; record `acknowledged_by_user_id` + `acknowledged_at`.
	- Findings are never deleted in the MVP.

## Non-Functional Requirements

- NFR1: Drift generation must be deterministic for the same baseline and scope.
- NFR2: Drift must remain tenant-scoped and safe to display.
- NFR3: Evidence minimization
	- `evidence_jsonb` must be sanitized (no tokens/secrets) and kept small.
	- MVP drift evidence should include only:
		- `change_type`
		- changed_fields / metadata summary (counts, field list)
		- run refs (baseline_run_id/current_run_id, timestamps)
	- No raw payload dumps.

## Dependencies / Name Resolution

- Drift/Audit UI should resolve labels via Inventory + Foundations (047) + Groups Cache (051) where applicable.
- No render-time Graph calls (Graph only in background sync/jobs, never in UI render).

## Success Criteria

- SC1: Admins can identify drift across supported types (Policies + Assignments) in under 3 minutes.
- SC2: Drift results are consistent across repeated generation for the same baseline.

## Out of Scope

- Automatic revert/promotion.
- Rule engine in MVP (Audit later), but the data model is prepared via `rule_id` / `control_id` / `expected_value`.

## Future Work (non-MVP)

- Security Suite Audits: add rule-based generators that write Findings (no new Finding model).
- Cross-tenant Compare: may write Findings (`finding_type=compare`) or emit a compatible format that can be stored as Findings.

## Related Specs

- Program: `specs/039-inventory-program/spec.md`
- Core: `specs/040-inventory-core/spec.md`
- Compare: `specs/043-cross-tenant-compare-and-promotion/spec.md`