# #1294 Phase 2 Rollup-Reference Test Migration Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Migrate analytics test and fixture coverage from aggregate formula authoring to the supported `rollupsummary` plus formula-reference contract, while keeping only narrow lower-layer legacy compatibility coverage until Phase 3.

**Architecture:** Treat user-facing cross-child aggregation as stored rollup data plus formula reference. Where legacy aggregate runtime must still be covered, test it below the authoring surface by constructing `AggregateExpr`, `AggregateJoinSpec`, or aggregate markers directly instead of authoring formula strings.

**Tech Stack:** Go tests, NexusCRM analytics formula-view and rollup packages, Markdown design docs

---

### Task 1: Land the Phase 2 design boundary in docs

**Files:**
- Create: `docs/superpowers/specs/2026-05-24-1294-phase2-rollup-reference-test-migration-design.md`
- Create: `docs/superpowers/plans/2026-05-24-1294-phase2-rollup-reference-test-migration.md`

- [ ] **Step 1: Capture the verified boundary**

Document that this repo has:

- Phase 1 merged
- legacy aggregate runtime still live
- supported stored-rollup formula reference coverage already on `main`
- no public-repo persisted aggregate-formula payload to justify a repo-local migration tool

- [ ] **Step 2: Freeze the stop-loss**

Document that this PR must not:

- delete runtime aggregate machinery
- invent tenant migration tooling without a target
- widen into `AVG` policy or general rollup substrate work

### Task 2: Rewrite supported semantic coverage to rollupsummary references

**Files:**
- Modify: `backend/internal/features/analytics/formula_view_rollup_parity_integration_test.go`
- Modify: `backend/internal/features/analytics/formula_view_service_test.go`
- Modify: `backend/internal/features/analytics/formula_view_dependencies_test.go`

- [ ] **Step 1: Rewrite the parity integration fixture**

Replace formula expressions like:

```go
Expression: "SUM(ChildRecord.Amount)"
```

with parent stored rollup columns and formulas that reference those stored fields.

Expected shape:

- parent table stores `SumAmount__c`, `CountAmount__c`, `AvgAmount__c`, `MinAmount__c`, `MaxAmount__c`
- test computes rollup values through `RollupRepository`
- test writes those values to the parent row
- formula view projects those stored fields or formula references to them

- [ ] **Step 2: Replace service-level positive aggregate authoring tests**

Reframe user-facing semantics around stored rollup references:

- validation accepts formulas that reference stored rollupsummary fields
- view DDL reads the stored parent column
- no aggregate JOIN is synthesized for that supported path

- [ ] **Step 3: Rewrite dependency coverage**

Change the dependency test from:

- "SUM(Child.Amount) creates no child-view dependency edge"

to:

- "a formula that references a stored rollupsummary field creates no child-view dependency edge"

### Task 3: Lower legacy compatibility coverage below the authoring surface

**Files:**
- Modify: `backend/internal/features/analytics/formula_dsl_compiler_test.go`
- Modify: `backend/internal/features/analytics/formula_dsl_viewbuilder_test.go`
- Modify: `backend/internal/features/analytics/formula_view_service_test.go`

- [ ] **Step 1: Replace parser-driven aggregate compiler tests**

Stop doing:

```go
ast, _ := Parse("SUM(WorkLog__c.Hours__c, ParentIssue__c)")
```

Instead build:

```go
ast := &AggregateExpr{Func: "SUM", ChildObject: "WorkLog__c", ChildField: "Hours__c", ForeignKey: "ParentIssue__c"}
```

and verify `compileAggregate(...)` or `compile(...)` emits the expected aggregate marker.

- [ ] **Step 2: Replace BuildViewDDL aggregate-authoring tests with marker/helper tests**

Where the current tests depend on formula text authoring like `SUM(WorkLog__c.Hours__c)`, rewrite them to call lower-layer helpers directly:

- `resolveAggregateMarkers(...)`
- `findAggregateJoinForMarker(...)`
- aggregate pass-through alias helpers where useful

The goal is to keep coverage for marker replacement semantics without teaching authored aggregate formulas as supported behavior.

- [ ] **Step 3: Move aggregate relationship-resolution checks to direct service helper tests**

For explicit foreign key, ambiguity, wildcard, and child-field resolution cases, call `resolveAggregateJoinSpec(...)` directly with constructed `AggregateExpr` values instead of validating through authored formula text.

### Task 4: Audit remaining supported-contract aggregate fixtures

**Files:**
- Inspect only; no mandatory code target

- [ ] **Step 1: Search for remaining positive aggregate formula fixtures in analytics tests**

Run:

```bash
rg -n 'Expression: "(SUM|COUNT|AVG|MIN|MAX)\(|Formula: .*"(SUM|COUNT|AVG|MIN|MAX)\(|Parse\("(SUM|COUNT|AVG|MIN|MAX)\(' backend/internal/features/analytics/*test.go
```

- [ ] **Step 2: Classify any remaining hits**

Allowed after Phase 2:

- Phase 1 rejection-path tests outside the positive supported-contract surface
- narrow lower-layer legacy compatibility tests whose purpose is explicitly transitional

Not allowed after Phase 2:

- tests whose user-facing contract still says aggregate formula authoring is supported

### Task 5: Final verification and commit

**Files:**
- Modified analytics tests
- New docs under `docs/superpowers/specs` and `docs/superpowers/plans`

- [ ] **Step 1: Run analytics verification after the last code change**

Run:

```bash
cd backend && go test ./internal/features/analytics -count=1
```

Expected: PASS for the full analytics package. If the integration parity test skips for local TiDB availability, report that explicitly; do not claim it executed if it skipped.

- [ ] **Step 2: Run repo hygiene check**

Run:

```bash
git diff --check
```

Expected: no whitespace or patch-format errors.

- [ ] **Step 3: Commit**

```bash
git add backend/internal/features/analytics docs/superpowers/specs/2026-05-24-1294-phase2-rollup-reference-test-migration-design.md docs/superpowers/plans/2026-05-24-1294-phase2-rollup-reference-test-migration.md
git commit -m "test(analytics): migrate aggregate fixtures to rollup references"
```