Core Data Impact Analysis

Entity: $ARGUMENTS

Required by ADR 007 (docs/architecture/007-core-data-change-process.md) before ANY schema changes.

Step 1: Read ADR 007

Read docs/architecture/007-core-data-change-process.md for the required process.

Step 2: Entity Audit

For the target entity, find and document:

Properties & Types

Search Models/<EntityName>+CoreDataProperties.swift for:

• All property names and their types
• Optional vs required
• Default values

Relationships

• All relationships and their inverses
• Cascade delete rules
• Nullify rules

Codegen Setting

• Class Definition (auto-generated) or Manual/None (custom extensions)?
• If Manual: what custom logic exists in extensions?

Fetch Indexes

• What fields are indexed?
• What predicates are commonly used?

Step 3: Usage Search

Search the entire codebase for references to this entity:

Services

Search Services/ for all methods that read or write this entity.

Views

Search forager/Views/ for @FetchRequest and other references.

Repositories

Search forager/Repositories/ for query methods.

Tests

Search foragerTests/ for test coverage.

Step 4: Impact Report

Produce a structured report:

## Core Data Impact Analysis: [EntityName]

### Current Schema
- Properties: [list with types]
- Relationships: [list with inverses]
- Codegen: [Class Definition / Manual]
- Indexes: [list]

### Files Affected by Change
- Services: [list]
- Views: [list]
- Repositories: [list]
- Tests: [list]

### Migration Impact
- Current model version: v6
- New version needed: v7
- Migration type: lightweight / manual
- CloudKit impact: [append-only constraint check]

### Risk Assessment
- [Identified risks]
- [Mitigation strategy]

Step 5: Scope-Aware Fetch Audit (ADR 013)

If the entity has a householdKey property, verify:

Fetch Scope Compliance

• Every fetchRequest() in services includes a householdKey predicate
• No unscoped fetches return user-facing data (ghost object risk)
• householdKey is passed as a parameter, not assumed from global state

Zone Safety

• Any overwrite/replace operation validates the target object is in an accessible store
• Pre-mutation cleanup runs before container.share() operations
• Orphaned objects (stale householdKey, parentless Ingredients) are handled

Entities requiring scope audit

Recipe, WeeklyList, MealPlan, PlannedMeal, Category, IngredientTemplate

See docs/architecture/013-scope-aware-fetch-pattern.md for the full pattern.

Step 6: Factory Compliance Check (ADR 014)

If the entity conforms to HouseholdScoped, verify:

• All creation sites use ManagedObjectFactory.make() (not direct Entity(context:))
• Services that create this entity have var factory: ManagedObjectFactory? property
• Factory is injected via foragerApp.init() or performScopedWrite
• Exempt sites documented: tests, previews, seeders, HouseholdService migration

Run /forager-architecture-audit to verify compliance.

HouseholdScoped entities: WeeklyList, Recipe, PlannedMeal, MealPlan, Category, IngredientTemplate

Critical Reminders

• CloudKit Production schema is append-only — no destructive changes
• New model version requires incrementing from v8 (current) — update as needed
• Test with sample data before migrating production
• Follow M3 Phase 3 pattern for migrations (successful isStaple migration)
• ADR 013: All service fetches on household-scoped entities MUST include householdKey predicate