← all branches

feat/sites-v2

needs attention
bf960ba · incrementalpre-PRreviewed 2026-08-12 05:48 UTC5H · 12M · 4L
The branch
Purpose
Establish a complete, adversarially-verified parity spec for the savings feature in the demo org — covering every legacy Niko field, its reachability class (PATCHABLE/DERIVABLE/ABSENT), and the exact code path to reach it.
Goal
Ship a demo savings view that never fabricates data, labels every gap honestly, and is verifiable by test or SQL query rather than eyeball.
Sub-goals
  • W1: Fix phantom metrics presence (highest-severity single defect)
  • W2: Make savings_reports nullable (migration 0065)
  • W3: Null-safe aggregation and window overlap fix
  • W4: Single Tinybird read + calc_role race condition fix (migration 0066)
  • W5: Honest baseline basis (delete fabricated B3, add invoice-reconstructed B4)
  • W6: Register extractors + meter timeline route
  • W7: Energy bank ledger on track U
  • W8: Data quality two-dimension + residual + uncaptured
  • W9: Two-track savings configs + calendar producer
  • W10: Identity assertions corrected (five-bar waterfall)
  • W11: UI components for the new data
  • W12: B2 CFE rate collection (deferred/gated)
The changes (whole branch)
What
Two planning documents added: savings-parity-gaps.md (exhaustive gap classification across 12 sections) and savings-parity-plan.md (implementation-ready W0-W12 work items with SQL and TypeScript verification specs). Supersedes prior drafts; incorporates findings from adversarial calculation (C-Dn) and UI (U-Dn) reviews.
Why
The prior draft had 20 confirmed defects (wrong baseline derivation, fabricated baselines, silenced phantom metrics, wrong window predicate, bank never running on track U, etc.). This plan is the corrected, adversarially-verified implementation contract.
Areas
docs/development/sites-devices-demo+1129−0packages/database/src/demo+1774−0.github/workflows+12−5.gitignore+5−0packages/database/package.json+4−0
Blast
11 files, +2924/−5 lines across docs + demo seed scripts + minor infra. Zero production code changes in this branch.
➖CI· no PR open➖CodeRabbit· no .coderabbit.yaml➖typecheck· doc-only change

Findings · 12

correctness1

medium

Wrong file attributed for metrics[gridVar] ?? 0 in gaps doc

docs/development/sites-devices-demo/savings-parity-gaps.md:59

Parent cell says savings-report-compute.shells.ts but code is in bill-compute.shells.ts.

security2

medium

New GET /sites/:id/meter-timeline route has no authorization spec

docs/development/sites-devices-demo/savings-parity-plan.md:323

W6 specifies no withAuth/RBAC/createRLSDb for the new route. Exposes meter serials and register values.

medium

RFC (Mexican tax ID) from prod fixture has no scrubbing guidance

packages/database/src/demo/extract-prod-fixture.ts:87

uc.rfc and uc.account_number extracted from prod. Fixture is gitignored but neither doc mandates synthetic replacements for demos.

conventions3

high

AbsentReason union in UI component — domain code cannot import it

docs/development/sites-devices-demo/savings-parity-plan.md:139

AbsentReason persisted to JSONB and emitted by shells, but defined in _components/honest/AbsentValue.tsx. Dependency inversion: must live in domains/utility/src/savings/savings.type.ts.

high

Five new *.decisions.ts files named after aspects, not entities

docs/development/sites-devices-demo/savings-parity-plan.md:304

baseline-basis, data-quality, energy-identity, savings-identity, track — lack canonical siblings. Use sub-entity directories or plain utility modules.

medium

compute* and resolve* prefixes used inside .decisions.ts files

docs/development/sites-devices-demo/savings-parity-plan.md:400

computeMeterRegisterResidual, computeUncaptured, resolveTrackPolicy should use decide* prefix per canonical form.

tests2

high

W4 spy targets tb.query which does not exist — TinybirdClient has queryPipe

docs/development/sites-devices-demo/savings-parity-plan.md:288

vi.spyOn(tb, "query") silently never fires. Must be queryPipe. Test will always pass vacuously.

high

W1 test asserts out.presence — field not in current ComputedOutputs

docs/development/sites-devices-demo/savings-parity-plan.md:197

presence is a new field added in W1 itself. Test cannot compile until the interface is extended.

improvement4

high

W4 must precede W6, not just W7 — W6 introduces the same race condition

docs/development/sites-devices-demo/savings-parity-plan.md:276

W6 adds mirror bill to same (contract, period) without calc_role dedup key, triggering delete-and-replace race before W7.

medium

W4 and W10 absent from gaps.md recommended order

docs/development/sites-devices-demo/savings-parity-gaps.md:178

Developer sequencing from gaps.md alone will miss the W4 prerequisite for W6/W7 and migration 0066.

medium

Migration ordering between 0065 (W2) and 0066 (W4) unspecified

docs/development/sites-devices-demo/savings-parity-plan.md:282

Both are pnpm db:generate outputs. Must merge 0065 before generating 0066 or second PR must regenerate.

medium

MCP tool sync for track param must be W9 deliverable, not conditional note

docs/development/sites-devices-demo/savings-parity-plan.md:435

track is added unconditionally to public-v1; MCP sync is always required. Should be in W9 Files section.

History · 7 commits

  1. bf960baneeds attentionincremental5H · 12M · 4L2026-08-12 05:48current
  2. eb284feneeds attentionincremental0H · 5M · 4L2026-08-12 05:10
  3. 6bfc5bcneeds attentionincremental4H · 7M · 6L2026-08-12 02:49
  4. 3d49126safeincremental0H · 0M · 2L2026-08-11 23:15
  5. df18b6bneeds attentionincremental2H · 5M · 5L2026-08-11 23:08
  6. 8b42c1eneeds attentionincremental0H · 2M · 3L2026-08-11 23:01
  7. 5c64ea3needs attentionfull3H · 4M · 5L2026-08-11 19:15