2487 — PUT singletons for explore/calculator provisioning¶
Problem¶
frontend/src/stores/workspace.ts provisioned the Simulator Explore
sandbox with a client-orchestrated GET → catch 404 → POST pair: two round
trips, the backend's "does this exist" decision left to frontend control
flow, and — because two tabs or a double-click both see 404 and both
POST — the exact race #2483/#2484 had to SAVEPOINT-guard. Separately,
CarbonReportService.create/bulk_upsert lazily created the unit's
Calculator carbon_projects row as a side effect of creating a report — a
write the caller never asked for, with nobody owning the project row's
lifecycle (ADR-014's "hidden side-effect write").
ADR-014 (014-backend-layering-workflows.md)
names this issue as its first real consumer: existence is an explicit
workflow step, never a branch discovered mid-request, and crossing
aggregates (CarbonProject, CarbonReport, CarbonReportModule) belongs in a
workflow, not smeared across a one-aggregate service.
Decision¶
Explore — one idempotent PUT, backed by a new workflow.
PUT /v1/carbon-reports/simulator/explore/unit/{unit_id}/reference-year/{reference_year}/
replaces the old POST at the same path; the frontend calls it
unconditionally. ExploreProvisioningWorkflow.ensure() is the one place
that decides "does this exist" — it calls CarbonReportService.get_explore
(read) then, if missing, CarbonReportService.create_explore (the
existing #2483-guarded project+report+modules create) and owns the commit
itself (workflows commit, services/repos never do). create_explore and
get_explore are left as they were — already correctly cross-aggregate and
covered by 15+ existing tests; the workflow is the new explicit "existence"
step ADR-014 asks for, not a rewrite of already-guarded internals. Always
returns 200 (create vs. return-existing isn't distinguished — nothing
downstream reads the status code differently, and a was_created flag
would be unused plumbing).
The GET route stays, unchanged in shape. resolveCarbonReportId in
frontend/src/stores/modules.ts is a genuine read-only consumer (no create
fallback) hit on cache-miss from ModuleTable/ModuleCharts/
HeadcountMemberSelect/print composables. "No backward-compat" targets the
GET-404-POST provisioning pair specifically — only POST is deleted.
Its TTL-refresh-scheduling logic (_refresh_explore_background, unchanged)
is now shared with PUT via one extracted helper
(_schedule_explore_refresh_if_stale) so staleness is defined once; PUT
needed it too because it now runs on every explore-page mount, the same
position the old GET-first flow occupied.
Path unchanged: /simulator/explore/..., not the issue's shorthand
/explore/.... Mirrors the existing GET/POST path exactly — renaming it
would be unrelated churn with no functional benefit, and "mirror, don't
invent" favors matching the established segment.
Calculator project — provisioned explicitly in unit_sync, not lazily.
CarbonReportService.create/bulk_upsert no longer self-provision a
missing Calculator project. create() still resolves a None
carbon_project_id (the POST /carbon-reports/ shape most callers use),
but read-only now — _get_project only, no _create_project fallback — and
raises ValueError naming the unit and the remedy ("run unit sync") when
none exists. bulk_upsert() now requires every item's carbon_project_id
already resolved and raises if not. New
CarbonReportService.ensure_calculator_projects(unit_ids) -> dict[int, int]
is the explicit provisioning step, reusing the existing #2483
SAVEPOINT-guarded _get_project/_create_project; unit_sync_handler
(app/tasks/unit_sync_tasks.py) calls it once per sync run, before
building the year's CarbonReportCreate batch, at the
"create_carbon_reports" phase where per-unit-year setup already happens.
This is a
single-aggregate operation (CarbonProject only) staying inside
CarbonReportService — no workflow forced onto a single INSERT, per
ADR-014's own scope guidance. year_configuration.py (year-config
creation) does not provision projects itself: it only fires the
unit_sync job, which is where units actually become known.
Accepted trade, flagged for the maintainer: a genuinely new unit whose
Calculator report is created (or CSV-ingested,
base_csv_provider.py:MODULE_PER_YEAR) before any unit_sync run for it
now fails loudly (ValueError → job ERROR / 500) instead of silently
self-provisioning. Every production caller was audited
(workspace_home.py is read-only and already 404s;
base_tableau_api_provider.py is read-only by its own comment; only
base_csv_provider.py's per-row fallback and POST /carbon-reports/ call
create with no project). This matches "no silent fallbacks," but is a real
behavior change worth the maintainer's eyes if it surfaces in practice.
Scoped out¶
- Splitting
CarbonProjecthandling out ofCarbonReportServiceinto its own one-aggregate service. ADR-014: existing service webs migrate opportunistically, not in a big-bang refactor. - A Postgres-testcontainer concurrency test for the PUT. The #2483
SAVEPOINT guards already have unit coverage for this exact race
(
test_create_explore_project_race_returns_winner,test_create_explore_report_race_returns_winner); the PUT route doesn't change that data-layer belt, so a new integration test would exercise the same guard a second time. repo.bulk_upsert'sON CONFLICT DO NOTHINGreturning only inserted rows** and **seed_helper.get_carbon_report_module_id` (confirmed zero callers). Both pre-existing, unrelated to this issue.- Regenerating
frontend/src/types/api/openapi.d.ts. Nothing statically imports the explore path's generated types (onlyconnectors.ts/auth.tsuse this file); regenerating needs a live backend this change doesn't require standing up.
Test¶
Backend (uv run pytest tests/unit):
tests/unit/workflows/test_explore_provisioning.py(new) —ExploreProvisioningWorkflow.ensure: returns the existing report without creating or committing; creates + commits when missing.tests/unit/v1/test_carbon_report.py— replaced the POST route tests with PUT route tests: creates when missing, returns existing without recreating, schedules background refresh when stale (mirrors the GET route's existing three TTL tests).tests/unit/services/test_carbon_report_service.py— new:ensure_calculator_projectscreates one project per unit and is idempotent;bulk_upsertpasses resolved ids through and raises on a missing one;createraises when no Calculator project exists. Existing tests that relied oncreate()'s removed lazy-provision now provision the project explicitly first (local_calculator_reporthelper); the statement-budget regression (#2449 Track B) updated for the now-smaller in-request project work.tests/unit/tasks/test_handler_registrations.py—unit_sync_handlertests mock the newensure_calculator_projectscall.tests/unit/services/test_simulator_plan_service.py,test_simulator_plan_reference_year_perf.py, and the PG integration testtests/integration/services/data_ingestion/test_simulator_plan_prefill_job_pg.py— their Calculator-report test helpers now provision the project explicitly first (same pattern).
Frontend: frontend/tests/unit/request-dedup.spec.ts's
explore-seed-cache scenario needed no change — its route mock matches
the URL regardless of HTTP method, and the success path was already one
request before this change (GET only; a POST fallback only fired on a
miss). Verified by inspection; a dedicated component test for the PUT
call itself was not added — putExploreCarbonReport is a two-line pass-
through over carbonReportLookupPath + api.put, already exercised
end-to-end by that spec's explore-seed-cache scenario and by
SimulationExplorePage's own Playwright coverage.
frontend/tests/integration/setup/simulator-mocks.ts's stateful fake
backend gated exploreReportCreated on method === 'POST' — updated to
'PUT', or every simulator-explore.spec.ts test would 404 on its first
request. Confirmed green locally: npm run build followed by
npx playwright test tests/integration/simulator-explore.spec.ts passes
28/28, run twice for stability. An earlier local attempt without a fresh
npm run build first produced a spurious openExplorer timeout
(.q-expansion-item never renders, likely a stale/missing dist/spa) —
that was a local-sandbox mistake, not a real gap. This suite is not part
of per-PR CI: it runs via test-frontend-integration in
.github/workflows/integration-tests.yml (nightly + workflow_dispatch +
pushes to ci-test/**), which does build first, same as this local run.
Deliverables¶
-
PUT /carbon-reports/simulator/explore/unit/{unit_id}/reference-year/{reference_year}/backed byExploreProvisioningWorkflow; old POST route deleted -
frontend/src/api/carbon_reports.ts(new) +workspace.ts'sselectSimulatorExploreCarbonReportcalls it unconditionally, no 404 branch -
CarbonReportService.create/bulk_upsertlazy project creation removed;ensure_calculator_projectsadded and called fromunit_sync_handler - Regression tests (workflow, PUT route, service fail-hard paths, unit_sync wiring) + test fallout fixed across 5 files
- Flip to
deliveredon merge