# Results Report Recipes

All recipes call the live Results Alpha surface. They do not include report formulas, norms tables, local dedupe, term parsing, test-result JSON parsing, growth-window switches, mastery math, next-task ranking, XP award math, XP-goal projection math, local time aggregation, or content-effectiveness counters.

Set credentials once:

```sh
export RESULTS_BASE_URL="${RESULTS_BASE_URL:-https://platform3-andymontgomery-9773s-projects.vercel.app/results/alpha/implementation/api}"
export RESULTS_TOKEN="${RESULTS_TOKEN:-$(curl -fsS -X POST "$RESULTS_BASE_URL/dev/mint?tenantId=demo" | jq -r '.token')}"
export COMMON_2025="subject=math&canonicalTermId=term_2025_26_spring&growthWindow=fall_to_spring&normsSet=2025"
export COMMON_2020="subject=math&canonicalTermId=term_2025_26_spring&growthWindow=fall_to_spring&normsSet=2020"
```

## QTI Attempt Report

Job: resolve one AlphaTest/QTI attempt to its settled mastery-gate result and evidence without scanning tenant results or maintaining consumer correlation state.

```sh
export QTI_ATTEMPT_ID="qti-attempt-alex-001"

curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/result-records?qtiAttemptId=$(printf '%s' "$QTI_ATTEMPT_ID" | jq -sRr @uri)" \
  -H "Authorization: Bearer $RESULTS_TOKEN" \
  | jq '{count, exact:.meta.exact, result:.data[0] | {representation_version,result_record_id,qti_attempt_id,administration_id,qti_session_id,qti_test_id,qti_artifact_version_id,content_test_spec_id,test_kind,gate_decisions,mastery_rows,kc_evidence_rows,kc_state_rows,test_result_components,references}}'
```

Require `count == 1`, `meta.exact == true`, and `representation_version == "results.qti_attempt_result.v1"`. Dereference the returned typed ids. Do not scan `result-records`, match `producer_result_id`, infer test kind from names/scores, or persist a shadow attempt map.

For a failed multi-item form, read exact remediation evidence without broadening a miss to the whole gate:

```sh
export RESULT_RECORD_ID="<settled-result-record-id>"

curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/missed-item-kc-attribution?resultRecordId=$(printf '%s' "$RESULT_RECORD_ID" | jq -sRr @uri)" \
  -H "Authorization: Bearer $RESULTS_TOKEN" \
  | jq '{status,attribution_ready,missed_question_count,unattributed_missed_question_count,data:[.data[]|{question_id,kc_refs,attribution_status}]}'
```

Require `attribution_ready == true` before routing by KC. If a row says `missing_kc_link`, fix the Content item mapping; never substitute every KC declared by the cumulative gate.

## Per-Student Learning Report

Job: regenerate the Alpha Learning Report sections for one student: placement and progress, course completion, MAP results, grade levels mastered, XP goals, time commitment, and accuracy.

Set the student once:

```sh
export LR_STUDENT="stu_timeback_10017"
export LR_SUBJECT="math"
export LR_AS_OF_DATE="2026-06-03"
export LR_TERM="term_2025_26_spring"
export LR_COURSE="course_algebra_1"
export LR_COMMON="subject=$LR_SUBJECT&canonicalTermId=$LR_TERM&growthWindow=fall_to_spring&normsSet=2025"
```

Placement and progress:

```sh
curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/students/$LR_STUDENT/track-state?subject=$LR_SUBJECT&asOfDate=$LR_AS_OF_DATE" \
  -H "Authorization: Bearer $RESULTS_TOKEN"

curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/students/$LR_STUDENT/working-grade?subject=$LR_SUBJECT&asOfDate=$LR_AS_OF_DATE" \
  -H "Authorization: Bearer $RESULTS_TOKEN"

curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/students/$LR_STUDENT/grades-mastered?subject=$LR_SUBJECT&asOfDate=$LR_AS_OF_DATE" \
  -H "Authorization: Bearer $RESULTS_TOKEN"
```

Use returned `placement_evidence`, `current_track_level_id`, `current_segment_id`, `working_grade`, mastery-pure `grades_mastered_sytd`, and `grades_mastered_sytd_formula_version`. `map_baseline_grade_delta_not_grades_mastered` and its formula version are placement/reporting context only and must never be labeled grades mastered. `advancement_value` is deprecated and must equal `grades_mastered_sytd`. Do not copy Curriculum track definitions or implement grade-movement formulas.

Regression cell: when `current_working_grade=8`, `sy_start_working_grade=6`, and `map_baseline_placement_grade=7`, require `grades_mastered_sytd=2` and `map_baseline_grade_delta_not_grades_mastered=1`. Any other naming or result is a Results contract failure, not a client formula choice.

Course completion:

```sh
curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/course-transcripts?studentId=$LR_STUDENT&courseId=$LR_COURSE&canonicalTermId=$LR_TERM" \
  -H "Authorization: Bearer $RESULTS_TOKEN"

curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/transcript-results?studentId=$LR_STUDENT&courseId=$LR_COURSE&canonicalTermId=$LR_TERM" \
  -H "Authorization: Bearer $RESULTS_TOKEN"
```

Use returned `course_attempt_result`, `earned_credits`, `attempted_credits`, `final_grade`, and `answer_precedence`. Do not parse Ed-Fi payloads or choose source precedence.

MAP results and grade levels mastered:

```sh
curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/students/$LR_STUDENT/map-scores?subject=$LR_SUBJECT&canonicalTermId=$LR_TERM&normsSet=2025" \
  -H "Authorization: Bearer $RESULTS_TOKEN"

curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/reports/growth-breakdown?$LR_COMMON&studentId=$LR_STUDENT" \
  -H "Authorization: Bearer $RESULTS_TOKEN"

curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/reports/student-progress-animation?$LR_COMMON&studentId=$LR_STUDENT" \
  -H "Authorization: Bearer $RESULTS_TOKEN"
```

Use returned `rit`, `percentile`, `observed_growth`, `projected_growth`, `growth_x`, `target_gap`, `working_grade`, `effective_grade`, and `levels_above_99`. Do not compute MAP, effective grade, Growth X, target gap, or 99-level values.

MAP percentile/RIT translation and legacy R90 norm-point fixtures:

```sh
curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/map-percentile-translations?subject=$LR_SUBJECT&gradeLevel=7&termSeason=spring&normsSet=2025&translationDirection=percentile_to_rit&inputPercentile=99" \
  -H "Authorization: Bearer $RESULTS_TOKEN"

curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/map-r90-norm-points?subject=$LR_SUBJECT&gradeLevel=7&termSeason=spring&normsSet=2025" \
  -H "Authorization: Bearer $RESULTS_TOKEN"
```

Use returned `output_rit`, `output_percentile`, `r90_rit`, `source_point_kind`, and `calculator_version` only for the documented Results report fixture. Do not use this endpoint as the GOALS RIT->grade source; use NWEAMAP `/nweamap/v1/r90*` or the Analytics R90 mirror. Do not ship a norms table, R90 table, or percentile/RIT calculator.

Group Growth X:

```sh
curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/reports/group-growth-x?$LR_COMMON&groupDimension=school_level" \
  -H "Authorization: Bearer $RESULTS_TOKEN"
```

Use returned `average_growth_x`, `student_count`, `excluded_student_count`, and `policy_version`. Do not calculate a group ratio from total observed and total projected growth; the surface owns the average-of-student-ratios rule.

XP goals and XP-goal projection evidence:

```sh
curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/students/$LR_STUDENT/growth-windows?subject=$LR_SUBJECT&canonicalTermId=$LR_TERM&growthWindow=fall_to_spring&normsSet=2025" \
  -H "Authorization: Bearer $RESULTS_TOKEN"

curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/students/$LR_STUDENT/xp-ledger" \
  -H "Authorization: Bearer $RESULTS_TOKEN"
```

Use returned `growth_x_target`, `on_track_for_growth_x_target`, `projected_gap`, `awarded_xp`, `expected_xp_ref`, `award_reason`, and `calculation_policy_ref`. Do not convert those values into remaining XP, hours-to-target, or a target date in client code. If a report asks for a combined GOALS projection field that is not returned by Results, stop and report the missing surface primitive.

Time commitment:

```sh
curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/reports/closed-loop-reconciliation?studentId=$LR_STUDENT&metricKind=minutes" \
  -H "Authorization: Bearer $RESULTS_TOKEN"
```

Use returned `activity_date`, `alpha_value`, and `reconcile_status` for minutes. Do not aggregate Events, rebuild a school-day calendar, or reconcile old TimeBack Production locally.

Accuracy:

```sh
curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/result-records?studentId=$LR_STUDENT&subject=$LR_SUBJECT&canonicalTermId=$LR_TERM" \
  -H "Authorization: Bearer $RESULTS_TOKEN"
```

Use returned `score_percent`, `mastery_cutoff_met`, `canonical_response`, and `is_correct` exactly as returned. For hierarchy or question response rows, read `test-result-components`; for model/prompt/overall/question feedback provenance, read `ai-grading-audit`. Do not rescore QTI responses, parse `canonical_response`, scrape grader logs, or decide mastery thresholds in the client.

## MAP Quadrants

Job: build the quadrant view for achievement versus growth.

```sh
curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/reports/map-quadrants?$COMMON_2025" \
  -H "Authorization: Bearer $RESULTS_TOKEN"
```

Use returned `quadrant`, `growth_x`, `rit`, and `intervention_flag`. Do not compute quadrant labels.

## Retake Audit

Job: show which sitting was selected and whether retakes or invalidations exist.

```sh
curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/reports/retake-audit?$COMMON_2025" \
  -H "Authorization: Bearer $RESULTS_TOKEN"
```

Use returned `sitting_count`, `highest_rit_sitting_id`, `deleted_sitting_count`, and `selection_explanation`. Do not choose the test of record.

## Growth Over Time

Job: render a longitudinal RIT and Growth X series.

```sh
curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/reports/growth-over-time?$COMMON_2025" \
  -H "Authorization: Bearer $RESULTS_TOKEN"
```

Sort by returned `term_order` if the UI needs ordering. Do not parse term names.

## Norms Isolation

Job: regenerate the same report under one explicit norms set.

```sh
curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/reports/norms-isolation?$COMMON_2025" \
  -H "Authorization: Bearer $RESULTS_TOKEN"

curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/reports/norms-isolation?$COMMON_2020" \
  -H "Authorization: Bearer $RESULTS_TOKEN"
```

The only change is `normsSet`. Do not mix 2020 and 2025 fields locally.

## Growth Breakdown

Job: show observed growth, projected growth, and Growth X components.

```sh
curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/reports/growth-breakdown?$COMMON_2025" \
  -H "Authorization: Bearer $RESULTS_TOKEN"
```

Display `observed_growth`, `projected_growth`, `growth_x`, and `target_gap` exactly as returned.

## Student Progress Animation

Job: render animation frames for grade movement over time.

```sh
curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/reports/student-progress-animation?$COMMON_2025" \
  -H "Authorization: Bearer $RESULTS_TOKEN"
```

Render one frame per returned row using `frame_index`, `frame_date`, `working_grade`, `effective_grade`, `growth_x`, and `levels_above_99`. Do not compute levels above 99.

## Closed-Loop Reconciliation

Job: prove old production and Alpha reconcile for the keys students live in.

```sh
curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/reports/closed-loop-reconciliation?$COMMON_2025" \
  -H "Authorization: Bearer $RESULTS_TOKEN"
```

Use `metric_kind`, keys, `old_value`, `alpha_value`, and `reconcile_status`. Do not reconstruct reconciliation in the client.

## Student Knowledge State

Job: show a student's four-state KC overlay for one subject as of a date.

```sh
curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/students/stu_timeback_10017/kc-state?subject=math&asOfDate=2026-06-03" \
  -H "Authorization: Bearer $RESULTS_TOKEN"
```

Use returned `initial_mastery`, `current_retention`, `durable_mastery`, `fluency_state`, `next_due_at`, `evidence_count`, `retention_model_ref`, `effective_at`, and `is_time_locatable`. Keep the four state fields separate. Do not blend them or recompute decay.

## Student Track State

Job: show where a student currently is on a Curriculum track.

```sh
curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/students/stu_timeback_10017/track-state?subject=math&asOfDate=2026-06-03" \
  -H "Authorization: Bearer $RESULTS_TOKEN"
```

Use returned `track_id`, `current_track_level_id`, `current_segment_id`, `placement_evidence`, `status`, `switched_to_track_id`, `effective_at`, and `is_time_locatable`. Do not copy Curriculum track, level, segment, course, or component definitions into the app.

## Next Task

Job: render the task the student should do next.

```sh
curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/next-task?studentId=stu_timeback_10017&subject=math&asOfDate=2026-06-03" \
  -H "Authorization: Bearer $RESULTS_TOKEN"
```

Use returned `task_type`, `task_ref_type`, `task_ref_id`, `reason`, `due_at`, `source_state_refs`, `policy_version`, and `null_reason`. Do not rank frontier lessons, reviews, practice, remediation, or gate retries locally.

## XP Ledger

Job: show awarded-XP history for one student.

```sh
curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/students/stu_timeback_10017/xp-ledger" \
  -H "Authorization: Bearer $RESULTS_TOKEN"
```

Use returned `xp_award_id`, `result_record_id`, `content_id`, `expected_xp_ref`, `awarded_xp`, `award_reason`, `calculation_policy_ref`, `source_evidence_refs`, `created_at`, and `reversal_of_xp_award_id`. Do not compute XP from events, gates, Content expected_xp, or engine output.

## Content Effectiveness

Job: show which Content items are being validated or failed by settled Results evidence.

```sh
curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/content-effectiveness?subject=math" \
  -H "Authorization: Bearer $RESULTS_TOKEN"
```

Use returned `validated_by_count`, `failed_by_count`, `effectiveness_rate`, `evidence_count`, `policy_version`, `source_result_refs`, and `last_recomputed_at`. Do not increment counters or recompute the rate in the app.

## Report Cards And Gates

Job: show durable report-card statements and mastery-gate decisions.

```sh
curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/students/stu_timeback_10017/report-card?subject=math&asOfDate=2026-06-03" \
  -H "Authorization: Bearer $RESULTS_TOKEN"

curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/students/stu_timeback_10017/gate-passes?subject=math&asOfDate=2026-06-03" \
  -H "Authorization: Bearer $RESULTS_TOKEN"
```

Use the effective-dated rows and `is_time_locatable`. Do not create a current-only shortcut.

## Working Grade And Named Grade Movement

Job: show current working level and mastery-pure grades mastered YTD, with MAP-baseline placement delta only as explicitly named context.

```sh
curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/students/stu_timeback_10017/working-grade?subject=math&asOfDate=2026-06-03" \
  -H "Authorization: Bearer $RESULTS_TOKEN"

curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/students/stu_timeback_10017/grades-mastered?subject=math&asOfDate=2026-06-03" \
  -H "Authorization: Bearer $RESULTS_TOKEN"
```

Display `grades_mastered_sytd` as the grades-mastered answer and its named formula version. If placement context is needed, display `map_baseline_grade_delta_not_grades_mastered` under that explicit label. Never call the MAP-baseline delta grades mastered and never implement either formula locally. The deprecated `advancement_value` and `formula_version` must exactly alias the mastery-pure pair.

## Academic Records And Transcript Answers

Job: answer transcript questions from settled Results views.

```sh
curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/academic-records?studentId=stu_timeback_10017&canonicalTermId=term_2025_26_spring" \
  -H "Authorization: Bearer $RESULTS_TOKEN"

curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/course-transcripts?studentId=stu_timeback_10017&courseId=course_algebra_1&canonicalTermId=term_2025_26_spring" \
  -H "Authorization: Bearer $RESULTS_TOKEN"

curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/course-grades?studentId=stu_timeback_10017&courseId=course_algebra_1" \
  -H "Authorization: Bearer $RESULTS_TOKEN"

curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/transcript-results?studentId=stu_timeback_10017&courseId=course_algebra_1&canonicalTermId=term_2025_26_spring" \
  -H "Authorization: Bearer $RESULTS_TOKEN"
```

Use returned `final_grade`, `final_numeric_grade`, `earned_credits`, `attempted_credits`, `course_attempt_result`, and `answer_precedence` exactly as returned. Ordinary reads intentionally omit source ids and evidence. Only an audit-authorized workflow may add `includeSourceEvidence=true`; its token must have ordinary read authority plus the exact `results:audit` scope, and the bounded field list is defined in `canonical-surface.md`. Do not parse Ed-Fi payload JSON or pick source precedence locally.

## Answer Keys

Job: verify a worked example without hardcoded expected hashes.

```sh
curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/reports/answer-key?normsSet=2025" \
  -H "Authorization: Bearer $RESULTS_TOKEN"
```

Compare a report response's `meta.resultHash` and `count` to the matching answer-key row. The expected hash comes from the surface.