← all branches

feat/int-base

needs attentionviewing older commit
ca45a96 · incrementalPR #268reviewed 2026-07-09 18:56 UTC0H · 3M · 3L · 4I
The branch
Purpose
Land every shared seam the 12 device-integration ports depend on — manifests, catalog seeds, ARN-seed registry entries, CDK path entries, and the legacy-registry/credential migration scripts — so each per-brand branch only touches its own vendor directories.
Goal
Enable per-brand branches to port legacy device integrations by providing all pre-declared paths, registrations, and tooling upfront.
Sub-goals
  • SG-1: 12 manifests + registration (hoymiles, shelly-cloud, solis, huawei-portal, solark, fronius, apsystems, abb, victron, enphase, sma, powerradar)
  • SG-2: Catalog seed rows (Makes, Integrations, MetricTypes incl. battery/load) — live idempotency proven
  • SG-3: ARN-seed REGISTRY entries + --only scoping
  • SG-4: CDK paths.ts handler entries (metrics/connection/explore/auth per vendor)
  • SG-5: D3 registry-migration script + 11 tests — dry-run/apply/rerun verified
  • SG-6: D2 credential-copy script + 19 tests — read-only dry-run verified
  • SG-N: Porting runbook + retired stale manifest co-location guidance; multi-granularity gotcha added to worker CLAUDE.md
The changes (whole branch)
What
Final commit (SG-N followup) adds the 'Support multiple granularities per device' gotcha rule to services/metrics/integrations/CLAUDE.md — 8 lines documenting groupChannelsByGranularity usage and failure semantics for brand integration implementers.
Why
The eGauge multi-granularity fix on feat/multi-gran surfaced a non-obvious implementation requirement (two-level skip hierarchy, transport-tag surfacing) that brand branch developers will need when porting their workers.
Areas
packages/integration-manifests+1062−2scripts/metrics+1602−0packages/database+257−14infra/cdk+185−0services/metrics/integrations+38−6domains/core+16−1domains/metrics+5−4
Blast
32 files, +3163/−27 across packages/integration-manifests (12 manifests + tests), scripts/metrics (new migration workspace), packages/database (seeds + schema), infra/cdk (paths only), services/metrics/integrations (docs), domains/core + domains/metrics (type widening, test fix). No stacks, no worker Lambdas, no prod runs.
doc-only-incremental-commit new-workspace-scripts-metrics no-stack-instantiation
➖CI· not accessible via token (HTTP 403)➖coderabbit· no .coderabbit.yaml in repo

Findings · 10

correctness1

low

Failure semantics underspecify which tag to surface when ALL granularities fail with distinct tags

services/metrics/integrations/CLAUDE.md

No guidance on first/worst/aggregate tag selection in the all-fail case.

security1

info

Transport tag surfaced to SFN — verify error mappers strip detail before external responses

services/metrics/integrations/CLAUDE.md:61

SFN-internal only. Not a current exposure.

conventions2

medium

Partial-failure semantic ('fail only if NONE produced points') not in metrics-pipeline.md

services/metrics/integrations/CLAUDE.md:62

The authoritative spec in metrics-pipeline.md's 'Multi-granularity per device' section does not document this failure policy. Should be documented there first before being prescribed here.

low

Cross-reference title is abbreviated vs actual section heading

services/metrics/integrations/CLAUDE.md:64

Actual heading: 'Multi-granularity per device (one variable at several cadences)'. Minor findability issue.

tests2

info

groupChannelsByGranularity is tested; multi-gran contract covered by eGauge + Growatt handler tests

services/metrics/integrations/CLAUDE.md

No test gap introduced by this change.

info

Helioscope has no multi-gran handler test

services/metrics/integrations/CLAUDE.md

Not a gap for this PR. Note if Helioscope gets a live-data worker.

improvement4

medium

'Skip a channel' conflates granularity-level (transport) and channel-level (translation) skips

services/metrics/integrations/CLAUDE.md:62

eGauge impl distinguishes transport errors (granularity-level, produces retryable tags) from TranslationFailed (channel-level). Conflating them causes workers to lose SFN retry eligibility on transient failures.

medium

'Surfacing the real transport tag' under-specified — no concrete code reference

services/metrics/integrations/CLAUDE.md:63

Suggest citing egauge/src/handlers/metrics.lambda.ts ~144-192 as the reference pattern (accumulate fetchErrors[], return fetchErrors[0] if payloads.length === 0). metrics-pipeline.md alone is too abstract for correct implementation.

low

No guidance that partial success rides existing InvocationSuccess shape

services/metrics/integrations/CLAUDE.md:62

Skipped channels are absent from MetricsPayload[] — no new result type needed. State explicitly to prevent developers inventing a partial-error sidecar.

info

groupChannelsByGranularity import may be confused with the descriptors-catalog ban (line 52)

services/metrics/integrations/CLAUDE.md:59

Import is tree-shaking safe. Consider adding 'safe — does not pull descriptors-catalog' to remove ambiguity.

History · 11 commits

  1. f7b9554safeincremental0H · 0M · 0L2026-07-13 20:18
  2. 9ca23adneeds attentionincremental0H · 3M · 3L2026-07-13 19:17
  3. 595484fneeds attentionincremental1H · 3M · 7L2026-07-13 04:29
  4. 2ed62f4safeincremental0H · 0M · 0L2026-07-13 04:13
  5. 2812f54needs attentionincremental1H · 3M · 10L2026-07-11 00:19
  6. 1794b23needs attentionincremental2H · 2M · 5L2026-07-10 21:59
  7. e5674dcneeds attentionincremental3H · 7M · 6L2026-07-09 19:29
  8. ca45a96needs attentionincremental0H · 3M · 3L2026-07-09 18:56current
  9. 5d19484safeincremental0H · 0M · 1L2026-07-08 02:04
  10. dd403feneeds attentionincremental12H · 22M · 12L2026-07-07 20:02
  11. e663ae9needs attentionincremental2H · 7M · 7L2026-07-07 19:02