← all branches

feat/metrics-agg

needs attentionviewing older commit
4849d9a · fullpre-PRreviewed 2026-07-07 18:54 UTC6H · 8M · 6L · 1I
The branch
Purpose
Implement read-time derivation engine so site-level totals can be derived from multiple node/device measurements without materializing in Tinybird.
Goal
resolveMetricStreamWindow handles internal:derivation sources by recursively resolving inputs, aligning slot grids, and evaluating a restricted arithmetic formula — transparent to SiteMetrics consumers.
Sub-goals
  • SG-1: Pure derivation evaluator (formula parser + slot alignment + strict policy) as decisions module
  • SG-2: Read-path integration — extend resolveMetricStreamWindow to detect derivation and invoke evaluator
  • SG-3: Seam verification + data-quality propagation + cross-org guard test
  • SG-4: E2E on preview with real multi-device total via seed data
  • SG-N: Docs + framework fold-back
The changes (whole branch)
What
Only .branch/scope.md updated — branch provisioned with new plan replacing prior feat/soft-launch scope.
Why
Multi-device site aggregation for billing requires combining measurements from N nodes into one site-level variable. Explicit derivation streams (opt-in, never auto-summed) are the safe, P7-preserving design.
Areas
.branch/scope.md+59−160
Blast
1 file (+59/−160) — provisioning-only, no code changed yet.
provisioning-only scope-review billing-grade-correctness
➖typecheck· provisioning-only commit — no code changed➖tests· provisioning-only commit — no code changed➖coderabbit· no .coderabbit.yaml in repo

Findings · 24

correctness5

high

Depth-at-read requires a depth counter not present in resolveMetricStreamWindow's signature

.branch/scope.md

high

Derived stream's granularitySeconds may resolve incorrectly in resolveSiteEnergyStreams

.branch/scope.md

medium

TinybirdClient must be threaded through recursive input resolution — not called out

.branch/scope.md

medium

Coverage clamp logic inverts for strict policy — min() must become max()

.branch/scope.md

low

DepthExceeded at read must be a hard error, never silent truncation

.branch/scope.md

security4

high

Formula parser not mandated safe — eval() injection risk unaddressed

.branch/scope.md

high

Cross-org input leak: RLS-only guard has no defense-in-depth

.branch/scope.md

medium

Fanout DoS: depth cap doesn't bound Tinybird read count — exponential fanout possible

.branch/scope.md

low

Write-time bypass: read-time DepthExceeded must be a hard error, not partial data

.branch/scope.md

conventions5

high

SG-2 places orchestration logic in metric.queries.ts, violating thin-wrapper convention

.branch/scope.md

medium

MAX_DERIVATION_DEPTH should move to lib/ to avoid sibling-module coupling

.branch/scope.md

medium

derivation/ module needs derivation.type.ts for evaluator input/output types

.branch/scope.md

low

DerivationConfig tightening should target source-config.types.ts not metric-source.type.ts

.branch/scope.md

low

No index.ts or FCIS namespace planned for derivation/ — export surface unresolved

.branch/scope.md

tests5

high

Tinybird mocking strategy unresolved — integration tests may be untestable in CI

.branch/scope.md

high

Cadence-mismatch test plan lacks a pinned numeric fixture

.branch/scope.md

medium

Cross-org derivation-input test underspecified — no function, file, or assertion named

.branch/scope.md

medium

SG-4 relies on manual hand-check — no automated regression for derivation→SiteMetrics seam

.branch/scope.md

low

P7 regression guard already covered by existing test suite

.branch/scope.md

improvement5

medium

Non-strict policy behavior undefined — success criterion untestable as written

.branch/scope.md

medium

Energy (kWh) downsampling rule missing — billing-correctness gap

.branch/scope.md

low

interval parameter forwarding to recursive input reads is unaddressed

.branch/scope.md

low

SG-4 preview data dependency is implicit — potential implementation blocker

.branch/scope.md

info

LCM phrasing adds noise — for real-world cadences it always equals coarsest

.branch/scope.md

History · 5 commits

  1. 6faff4bneeds attentionincremental0H · 2M · 6L2026-07-10 00:01
  2. d75e738needs attentionincremental0H · 2M · 5L2026-07-09 19:39
  3. 17b6060needs attentionfull2H · 10M · 8L2026-07-09 18:48
  4. 6580b91needs attentionincremental2H · 9M · 11L2026-07-09 02:06
  5. 4849d9aneeds attentionfull6H · 8M · 6L2026-07-07 18:54current