# Feature Specification: SoT Foundations & Assignments

**Feature Branch**: `006-sot-foundations-assignments`  
**Created**: 2025-12-25  
**Status**: Draft  
**Input**: User description: "SoT Foundations & Assignments: implement backup/restore foundations (assignment filters, scope tags, notification templates) and add assignment-aware backup/restore pipeline with ID mapping for core Intune objects; keep Conditional Access restore preview-only until named locations/mapping exist."

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Restore Foundations First (Priority: P1)

As an admin, I want to back up and restore the core "foundation" objects that other configurations depend on (assignment filters, scope tags, and compliance notification templates), so that later restores can reliably re-apply assignments and dependencies.

**Why this priority**: Without these foundations, restores either fail or must skip assignments/dependencies, which reduces trust and makes outcomes unpredictable.

**Independent Test**: In a test tenant with at least one filter, one scope tag, and one notification template: create a backup snapshot, then restore into a tenant where they are missing. Verify that the restored objects exist and that a mapping from old IDs to new IDs is produced.

**Acceptance Scenarios**:

1. **Given** a tenant with assignment filters, **When** a backup is created and later restored into a tenant missing those filters, **Then** missing filters are created and the restore reports the old→new identifier mapping.
2. **Given** a tenant with scope tags, **When** a restore runs, **Then** scope tags are restored before any dependent objects are applied.
3. **Given** a tenant with compliance notification templates, **When** a restore runs, **Then** templates are restored before applying compliance policy scheduled actions.

---

### User Story 2 - Apply Assignments Safely (Priority: P2)

As an admin, I want restores to apply assignments for supported configuration objects using the foundation mappings, so that a restore reproduces intended targeting while staying safe and auditable.

**Why this priority**: Restoring payloads without assignments is incomplete; restoring assignments without safe mapping can be dangerous.

**Independent Test**: Restore a small set of supported configurations that include assignments with filters and scope tags. Verify that assignments are applied when mappings exist, and skipped with a clear reason when mappings are missing.

**Acceptance Scenarios**:

1. **Given** a configuration object whose assignments reference filters/scope tags that exist (or can be mapped), **When** restore executes, **Then** assignments are applied and reported as applied.
2. **Given** a configuration object whose assignments reference a missing dependency (e.g., an unknown filter), **When** restore executes, **Then** the assignment is skipped (not broadly applied) and a human-readable reason is recorded.
3. **Given** an object restore with name collisions, **When** the system cannot unambiguously match a target, **Then** it creates a copy with a predictable suffix and records this decision in the restore report.

---

### User Story 3 - Conditional Access Stays Preview-Only (Priority: P3)

As an admin, I want to preview Conditional Access (CA) policies and their dependencies, but I do not want CA restore to execute automatically until dependency mapping is supported.

**Why this priority**: CA is security-critical and often depends on other objects (like named locations) and identity references. A preview still delivers value without risking outages.

**Independent Test**: Include CA policies in a backup and run restore in "preview" mode. Verify preview shows intended actions and highlights missing dependencies, while execute mode does not apply CA changes.

**Acceptance Scenarios**:

1. **Given** a backup containing CA policies, **When** a restore preview is generated, **Then** CA items appear in preview with a clear "preview-only" indicator.
2. **Given** a restore execution (non-dry-run), **When** CA items are included, **Then** the system does not apply CA changes and records them as preview-only/skipped.

### Edge Cases

- Missing permissions: backup/restore continues for other object types and clearly reports which categories failed due to permissions.
- Name collisions: multiple objects share the same display name; system must avoid ambiguous updates.
- Missing identity references: group/user references cannot be resolved; system must skip the assignment and report.
- Large tenants: operations must cope with pagination and partial failures without losing auditability.
- Throttling/transient failures: system retries safely and produces a final report if some items could not be processed.

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: System MUST support backup and restore of foundation objects: assignment filters, scope tags, and compliance notification templates.
- **FR-002**: System MUST restore foundation objects before applying any dependent configurations.
- **FR-003**: System MUST produce an identifier mapping report (old→new) for restored foundation objects.
- **FR-004**: System MUST apply assignments for supported configurations using the identifier mapping.
- **FR-005**: System MUST skip assignments that cannot be safely mapped (e.g., missing dependencies) and MUST record a clear skip reason.
- **FR-006**: System MUST be able to run in preview mode that produces the same decision report as execute mode, without making changes.
- **FR-007**: System MUST NOT delete objects in the target tenant as part of restore.
- **FR-008**: System MUST record an audit trail for backup and restore actions, including outcomes, partial failures, and skipped items.
- **FR-009**: System MUST prevent conflicting simultaneous restore executions for the same tenant (single-writer safety).
- **FR-010**: System MUST keep Conditional Access restore as preview-only until dependency mapping for CA is supported.

### Key Entities *(include if feature involves data)*

- **Foundation Object Snapshot**: A captured representation of an assignment filter, scope tag, or notification template.
- **Assignment Snapshot**: Captured targeting rules associated with a configuration object.
- **Restore Mapping**: A mapping of source identifiers to newly created target identifiers.
- **Restore Report**: A structured outcome summary containing applied items, skipped items, reasons, and any created copies.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: In a tenant with at least 10 foundation objects, a full foundations restore completes with ≥ 99% of items either applied or explicitly skipped with a reason.
- **SC-002**: For supported configuration objects with assignments, ≥ 95% of assignments are either applied correctly or skipped with a clear reason (no silent failures).
- **SC-003**: Restore preview generation for 100 selected items completes in under 2 minutes in a typical admin environment.
- **SC-004**: Admins can complete a restore workflow (preview → execute) with no ambiguous outcomes: every selected item ends in Applied / Created Copy / Skipped / Failed with a recorded reason.
