Store household calculation outputs in Simulation records instead of Report #235

SakshiKekre · 2025-10-09T01:14:44Z

Fixes #226

Problem

Household calculation outputs were incorrectly stored in Report.output due to economy calculation limitations being applied to household calculations. Ideally, each Simulation should store its own output.

Solution Overview

Implemented a callback-based flow where the Handler manages per-simulation execution and the Manager orchestrates storage via callbacks.

Architecture Changes

Added simulationIds to CalculationMeta

Why: The handler needs to know which simulations to run calculations for. Critical for the waterfall pattern (direct URL navigation/page refresh) where metadata must be reconstructed from the report.

Handler Executes Multiple Simulations

Why: Each simulation needs its own calculation with its own policy (baseline vs reform).

Unique tracking keys: Uses ${reportId}-sim-${simulationId} to avoid handler collisions
Positional mapping: simulationIds[0] → baseline, simulationIds[1] → reform (matches report structure)
Synthetic progress: Aggregates progress across all simulations for a report
Callback coordination: Wraps onSimulationComplete callback to detect when all simulations are done and trigger onComplete

Manager Provides Storage Callbacks

Why: Separation of concerns - Handler handles calculation logic, Manager handles storage/side effects (dependency inversion).

Dependency injection via callbacks: Standard pattern (used in React, Express, event emitters)
Progressive updates: Each simulation output stored immediately via onSimulationComplete
Report completion: Final report status updated via onComplete after all simulations finish

Related Backend Changes (policyengine-api)

Service: Added update_simulation_output() to SimulationService
Routes: Added PATCH /{country}/simulation endpoint (ID in payload, not URL)
Database: Updated initialise.sql and initialise_local.sql with output_json column

The Complete Flow

Manager calls Service's executeCalculation() with callbacks
Service routes to Handler based on calculation type
Handler loops through meta.simulationIds
For each simulation:
- Handler executes calculation → calls onSimulationComplete → Manager stores in Simulation
After all simulations complete:
- Handler calls onComplete → Manager stores Report with output={}

vercel · 2025-10-09T01:14:48Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
policyengine-app-v2	Ready	Preview	Comment	Oct 15, 2025 5:36am

anth-volk

Thanks for this, Sakshi. TL;DR: I'd move the executeCalculation code to the household-level handler instead.

anth-volk · 2025-10-09T17:29:14Z

app/src/libs/queryOptions/calculations.ts

+      // Simulation IDs needed for storing household calculation outputs
+      simulationIds: [
+        String(report.simulation_1_id),
+        ...(report.simulation_2_id ? [String(report.simulation_2_id)] : []),


nit: Make this less hacky; I was about to write an issue asking if this didn't nest sim 2's ID inside an array, inside another array, until I re-read the manipulation code

anth-volk · 2025-10-09T17:36:33Z

app/src/libs/calculations/service.ts

+      for (let index = 0; index < meta.simulationIds.length; index++) {
+        const simulationId = meta.simulationIds[index];
+        const policyId = index === 0 ? meta.policyIds.baseline : meta.policyIds.reform;
+
+        if (!policyId) {
+          continue;
+        }
+
+        const singleSimMeta: CalculationMeta = {
+          ...meta,
+          policyIds: { baseline: policyId, reform: undefined },
+          simulationIds: [simulationId],
+        };
+
+        await this.householdHandler.execute(
+          `${reportId}-sim-${simulationId}`,
+          singleSimMeta,


issue, blocking: I'd highly recommend modifying the household handler instead.

The aim of executeCalculation is to occur at the report level, executing an entire report's worth of calculation. In the long-run, with API v2, ideally we'd just move the functionality to the simulation level, which would make this easier. For the time being, with households having a sim-level calculation, it'd be more effective to add the onSimulationComplete function to the handler itself and return the calculation service code back to what it was, I think.

…mulations

anth-volk

@SakshiKekre left some commentary on this.

anth-volk · 2025-10-15T19:39:31Z

app/src/hooks/useReportData.ts

+  const { data: simulationData } = useQuery({
+    queryKey: ['simulation', reformSimId || 'none'],
+    queryFn: () => fetchSimulationById(metadata!.countryId, reformSimId!),
+    enabled: !!baseReportId && outputType === 'household' && !!reformSimId,


question: Are you doing only the reform because in a next PR, you'll add the code for the comparison?

anth-volk · 2025-10-15T19:40:30Z

app/src/hooks/useReportData.ts

+    if (parsed.countryId && parsed.householdData) {
+      // Already a Household object, just add the ID
+      output = {
+        ...parsed,
+        id: baseReportId,
+      };
+    } else {
+      // Raw HouseholdData, need to wrap it
+      const wrappedOutput: Household = {
+        id: baseReportId,
+        countryId: metadata!.countryId,
+        householdData: parsed,
+      };
+      output = wrappedOutput;
+    }


question: Why is this necessary?

anth-volk · 2025-10-15T19:45:30Z

app/src/libs/calculations/handlers/household.ts

+    const allCompleted = simulations.every((sim) => sim.completed);
+    const anyError = simulations.some((sim) => sim.error);
+


question: If a user runs, say, 4 household calculations within 5 minutes, won't this require all 4 to be complete to show any household report as complete?

anth-volk · 2025-10-15T19:46:49Z

app/src/libs/calculations/manager.ts

-      meta.type === 'household' ? onComplete : undefined
-    );
+    // Execute calculation with callbacks
+    const result = await this.service.executeCalculation(reportId, meta, callbacks);


question: Are you sure this and the above section don't break society-wide calculations?

SakshiKekre force-pushed the fix/issue-226-household-simulation-outputs branch from d42b8b5 to 89e7e66 Compare October 9, 2025 01:26

vercel bot deployed to Preview October 9, 2025 01:27 View deployment

vercel bot deployed to Preview October 9, 2025 01:44 View deployment

SakshiKekre mentioned this pull request Oct 9, 2025

Update simulation (for app v2) to store output for household calculations PolicyEngine/policyengine-api#2827

Merged

SakshiKekre requested a review from anth-volk October 9, 2025 05:17

SakshiKekre marked this pull request as draft October 9, 2025 05:17

SakshiKekre marked this pull request as ready for review October 9, 2025 15:11

anth-volk requested changes Oct 9, 2025

View reviewed changes

SakshiKekre added 4 commits October 12, 2025 15:09

feat/fix: Store household calculation outputs in Simulation records

1d266fd

fix: Update test to expect simulationIds

e6d3fbb

fix: Some more test fixes

cbbaf20

fix: Refactor household report calculation handler to run multiple si…

d7933cd

…mulations

SakshiKekre force-pushed the fix/issue-226-household-simulation-outputs branch from f979b9b to d7933cd Compare October 15, 2025 05:35

vercel bot deployed to Preview October 15, 2025 05:36 View deployment

SakshiKekre requested a review from anth-volk October 15, 2025 12:49

anth-volk reviewed Oct 15, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Store household calculation outputs in Simulation records instead of Report #235

Store household calculation outputs in Simulation records instead of Report #235

Uh oh!

SakshiKekre commented Oct 9, 2025 •

edited

Loading

Uh oh!

vercel bot commented Oct 9, 2025 •

edited

Loading

Uh oh!

anth-volk left a comment

Uh oh!

anth-volk Oct 9, 2025

Uh oh!

anth-volk Oct 9, 2025

Uh oh!

anth-volk left a comment

Uh oh!

anth-volk Oct 15, 2025

Uh oh!

anth-volk Oct 15, 2025

Uh oh!

anth-volk Oct 15, 2025

Uh oh!

anth-volk Oct 15, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		const allCompleted = simulations.every((sim) => sim.completed);
		const anyError = simulations.some((sim) => sim.error);

Store household calculation outputs in Simulation records instead of Report #235

Are you sure you want to change the base?

Store household calculation outputs in Simulation records instead of Report #235

Uh oh!

Conversation

SakshiKekre commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel bot commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

anth-volk left a comment

Choose a reason for hiding this comment

Uh oh!

anth-volk Oct 9, 2025

Choose a reason for hiding this comment

Uh oh!

anth-volk Oct 9, 2025

Choose a reason for hiding this comment

Uh oh!

anth-volk left a comment

Choose a reason for hiding this comment

Uh oh!

anth-volk Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

anth-volk Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

anth-volk Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

anth-volk Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

SakshiKekre commented Oct 9, 2025 •

edited

Loading

vercel bot commented Oct 9, 2025 •

edited

Loading