# Project State

## Project Reference

See: .paul/PROJECT.md (updated 2026-05-21)

**Core value:** Android devs plot 200Hz+ multi-signal sensor data without frame drops
**Current focus:** v0.4.0 portfolio hardening SHIPPED — next v0.5.0 architecture + interaction

## Current Position

Milestone: v0.5.0-architecture (NEXT)
Phase: 0 of N — Planned, not started
Plan: .paul/phases/v0.5.0-architecture-plan.md
Status: Awaiting kickoff
Last completed: v0.4.0 portfolio hardening (2026-05-21)
Last activity: 2026-05-21 — v0.4.0 closed via kmp-manager group-by-group flow. 8 P-groups executed. 15 plan tasks done. 107 tests pass (was 33). ABI lockdown active. Compose snapshot thread-safe.

Progress:
- v0.1.0 milestone: [██████████] 100% SHIPPED
- v0.2.0 milestone: [██████████] 100% SHIPPED
- v0.3.0 milestone: [██████████] 100% SHIPPED
- v0.4.0 milestone: [██████████] 100% SHIPPED

## Loop Position

```
PLAN ──▶ APPLY ──▶ UNIFY
  ✓        ✓        ✓     [v0.4.0 portfolio hardening SHIPPED — v0.5.0-SNAPSHOT]
```

## Accumulated Context

### Decisions

| Decision | Phase | Impact |
|----------|-------|--------|
| Canvas custom rendering (no lib) | Init | Core architecture |
| Render/data decoupled withFrameNanos | Init | RenderLoop design |
| TieredBuffer over flat ring | v0.2.0 | O(N×constant) memory, 20+ signals |
| MIN_MAX tier binning (not MEAN) | v0.2.0 | Composable, no artifacts at tier boundaries |
| MEAN removed from LodMode | v0.2.0 | Cleaner API, no synthetic values |
| LodDecimator as class (pre-alloc scratch) | v0.2.0 | Zero GC at render time |
| Sensor cap 200Hz (5_000μs) | v0.2.0 | Thermal/battery optimization |
| Package dev.dtrentin | v0.2.0 | Personal project, not company |
| iOS targets shipped | v0.3.0 | iosX64/iosArm64/iosSimulatorArm64 + Platform.ios.kt |
| iOS build pipeline green | v0.3.0 iOS | 33 tests pass on iOS sim, XCFramework "ChartRealtime" produced |
| timeIntervalSinceReferenceDate + epoch offset | v0.3.0 iOS | K/Native binding doesn't expose timeIntervalSince1970; use 978_307_200s constant |
| applyDefaultHierarchyTemplate() explicit | v0.3.0 iOS | iosMain/iosTest auto-wired across 3 iOS targets |
| Manual format helpers in AxisRenderer | v0.3.0 iOS | String.format JVM-only; private formatFixed/formatScientific/pow10 |
| kotlin.concurrent.Volatile + kotlin.jvm.JvmName imports | v0.3.0 iOS | Multiplatform replacements for JVM-default annotations |
| MIT License | v0.4.0 T1 | Personal project, permissive, no patent grant required |
| explicitApi() Strict + BCV 0.16.3 + klib enabled | v0.4.0 T2 | ABI lockdown active; chart-realtime.api 161 LOC + .klib.api 211 LOC baseline |
| kotlinx-datetime 0.6.2 (NOT 0.7.x) | v0.4.0 T4 | Kotlin 2.1.0 compat; bump to 0.7.x when Kotlin → 2.1.20+ in v0.5.0 |
| CircularBuffer.writeIndex Long | v0.4.0 T5 | Overflow 124d @ 200Hz fixed |
| hasData boolean flag | v0.4.0 T8 | Replace Float.MAX_VALUE/POSITIVE_INFINITY sentinels in TieredBuffer + RealtimeChart |
| _signals as @Volatile copy-on-write Map | v0.4.0 T9 | Replace MutableState<Map>; eliminate snapshot writes from data thread for collection |
| dataVersion as mutableLongStateOf | v0.4.0 T10 | Compose-observable; drives recomposition data-driven; idle = 0 recompositions |
| applySnapshot retry helper (Snapshot.withMutableSnapshot + SnapshotApplyConflictException) | v0.4.0 T9 | Thread-safe push from background thread |
| RenderLoop.kt deleted | v0.4.0 T6/T10 | rememberFrameTick removed; targetFps deprecated (KDoc + @Deprecated) |
| Per-signal scratch arrays in SignalEntry | v0.4.0 T11 | Single buffer snapshot per signal per frame (was 2); ~1.14 MB/signal |
| M4 binning (firstTs/V, minTs/V, maxTs/V, lastTs/V) | v0.4.0 T12 | Replace double-push min/max sentinel; TIER1/2 CAPACITY *4; no vertical spikes at bin boundaries |
| NaN/Inf/backward-timestamp guards on push | v0.4.0 T13 | Silent drop; KDoc contract added; per-signal lastPushedTs tracking |
| NumberFormat internal object | v0.4.0 T14 | Extracted from AxisRenderer for testability; 38 tests pinned behavior |

### Deferred Issues

| Issue | Origin | Effort | Revisit |
|-------|--------|--------|---------|
| ~~Dirty flag render (skip frame if no new data)~~ | v0.2.0 | S | ✓ v0.3.0 |
| ~~targetFps=30 default~~ | v0.2.0 | S | ✓ v0.3.0 |
| ~~iOS expect/actual beyond currentTimeMs~~ | Init | L | ✓ v0.3.0 |
| ~~KDoc on public API surface~~ | v0.2.0 | M | ✓ v0.3.0 |
| ~~README with integration example~~ | v0.2.0 | S | ✓ v0.3.0 |
| ~~iOS build/test pipeline (compile + iosTest + XCFramework)~~ | v0.3.0 plan | M | ✓ v0.3.0 iOS |
| Publish to Maven Central / GitHub Packages | v0.2.0 | M | v1.0.0 |
| iOS demo app (SwiftUI) | v0.3.0 iOS | L | v1.0.0 |
| CI workflow for iOS build (GitHub Actions) | v0.3.0 iOS | M | v1.0.0 |
| Compose compiler unstable warning on SignalConfig | v0.3.0 iOS | S | v0.5.0 |
| ~~LICENSE missing~~ | v0.4.0 plan | S | ✓ v0.4.0 T1 (MIT) |
| ~~explicitApi + BCV~~ | v0.4.0 plan | M | ✓ v0.4.0 T2 |
| ~~Internal lockdown 6 leaked symbols~~ | v0.4.0 plan | M | ✓ v0.4.0 T3 |
| ~~Drop expect/actual currentTimeMs~~ | v0.4.0 plan | S | ✓ v0.4.0 T4 |
| ~~CircularBuffer.writeIndex Long~~ | v0.4.0 plan | S | ✓ v0.4.0 T5 |
| ~~@Suppress + !! cleanup~~ | v0.4.0 plan | S | ✓ v0.4.0 T6 |
| ~~Dead config removal~~ | v0.4.0 plan | S | ✓ v0.4.0 T7 |
| ~~POSITIVE_INFINITY sentinel replace~~ | v0.4.0 plan | S | ✓ v0.4.0 T8 |
| ~~Compose snapshot thread safety~~ | v0.4.0 plan | M | ✓ v0.4.0 T9 |
| ~~dataVersion mutableLongStateOf~~ | v0.4.0 plan | M | ✓ v0.4.0 T10 |
| ~~Single snapshot per signal per frame~~ | v0.4.0 plan | M | ✓ v0.4.0 T11 |
| ~~M4 binning Tier1/Tier2~~ | v0.4.0 plan | M | ✓ v0.4.0 T12 |
| ~~NaN/Inf/backward-timestamp guards~~ | v0.4.0 plan | S | ✓ v0.4.0 T13 |
| ~~AxisRenderer format helpers test~~ | v0.4.0 plan | M | ✓ v0.4.0 T14 (38 tests) |
| ~~TieredBuffer + LTTB test gap~~ | v0.4.0 plan | M | ✓ v0.4.0 T15 (25 tests) |
| Bump kotlinx-datetime 0.6.2 → 0.7.x | v0.4.0 T4 | S | v0.5.0 (needs Kotlin 2.1.20+) |
| Long overflow at |value| ≥ 1e19 in NumberFormat.formatFixed | v0.4.0 T14 | S | v0.5.0 (currently safe via routing) |
| LTTB upper bound inclusive vs snapshot half-open semantic mismatch | v0.4.0 T15 | S | v0.5.0 |
| Remove ChartConfig.targetFps (now @Deprecated, ignored) | v0.4.0 T10 | S | v0.5.0 |
| Memory budget: ~1.14 MB/signal post-CAPACITY *4 (was ~760 KB pre-bump) | v0.4.0 T12 | doc | document in README post-v0.4.0 |

### Reviewer Audit Findings (2026-05-21)

Source: 3 parallel reviewer agents (android-reviewer + mobile-performance-reviewer + mobile-architect).

**S0 (block portfolio) findings:**
- LICENSE missing → legalmente nessuno può usare la lib
- Compose snapshot violation: `push()` mutate MutableState da thread arbitrario senza withMutableSnapshot
- `dataVersion @Volatile` NON è Compose-observable, recomposition driven solo da frameTick side-effect
- Render NON zero-alloc: Pair + Stroke + TextLayoutResult + Strings per tick per frame (~50-100 KB/s)
- Snapshot doppia per signal per frame (8x lavoro su 4 segnali)
- No interaction layer (touch/zoom/pan) → fatale per "real-time chart" piece

**S1 (visibili) findings:**
- CircularBuffer.writeIndex Int overflow dopo 124 giorni @ 200Hz
- Tier1/Tier2 binning C7 artifacts (push doppio min poi max stesso ts)
- 6 leaked internal symbols pubblici (CircularBuffer, TieredBuffer, LodDecimator, dataVersion, rememberFrameTick, capacity constants)
- 3 dead config field (maxBufferSeconds, xLabelDecimals, SignalConfig.label)
- `@Suppress("UNUSED_EXPRESSION")` hack + `!!` non-null assertion in render hot path
- Test gap: AxisRenderer format helpers untested + buggy (Q4 formatFixed Long overflow), TieredBuffer untested (143 LOC), LTTB branch untested
- `expect/actual currentTimeMs` over-engineered — kotlinx-datetime 0.7.0+ replaces it
- iOS targets build ma README + samples Android-only

**Claims aggiustati:**
- "Zero GC at render time" → **falso oggi**, vero post v0.5.0 T8/T9
- "Lock-free SPSC ring buffer" → impreciso, fragile JMM su Native
- "200Hz sustained" → plausibile JVM, borderline mid Android multi-signal pre-v0.5.0 T11
- "1h buffer" → vero ma costa 720KB+ per signal (non documentato)

**Posizionamento mercato:**
Nicchia genuinamente vuota: nessun KMP chart lib (Vico, KoalaPlot, AAY-chart, netguru) targeta real-time 200Hz multi-signal con bounded memory. Differentiation reale ma serve interaction layer per essere prendibile sul serio.

### Blockers/Concerns
- ~~LICENSE missing~~ → ✓ MIT shipped in v0.4.0 T1
- ~~API surface non lockdown~~ → ✓ explicitApi + BCV shipped in v0.4.0 T2-T3
- ~~Compose snapshot thread safety~~ → ✓ withMutableSnapshot + retry shipped in v0.4.0 T9
- No interaction layer (touch/zoom/pan) → blocking "real-time chart" claim (v0.5.0 scope)
- targetFps deprecated but not removed → minor noise in public API (v0.5.0)

## Session Continuity

Last session: 2026-05-21 (v0.4.0 portfolio hardening shipped via kmp-manager group-by-group flow)
Stopped at: v0.4.0 closed. 15 plan tasks done. 107 tests pass. Full verify suite green.
Next action: kickoff v0.5.0 architecture + interaction layer
Resume context:
- Library: chart-realtime, dev.dtrentin:chart-realtime:0.5.0-SNAPSHOT (version unbumped post-v0.4.0; bump deferred to v1.0.0 release)
- App: AndroidChartsApp consuming library, builds clean
- Remote: ssh://git@3nt-git.duckdns.org:222/davide.trentin/KMPCharts.git
- Package: dev.dtrentin.chart
- iOS: 3 targets compile, link, test (107 tests). XCFramework name `ChartRealtime`, baseName CamelCase.
- Local Mac setup: Xcode.app at /Applications/Xcode.app, iOS sim runtime installed (iPhone 17 family), local.properties points to ~/Library/Android/sdk, JDK 21 Temurin via JAVA_HOME.
- ABI baseline committed: chart-realtime/api/chart-realtime.api (161 LOC) + chart-realtime.klib.api (211 LOC)
- Plans: v0.4.0 ✓ SHIPPED · v0.5.0 + v1.0.0 PLANNED
- Effort residuo verso v1.0.0: ~7-10 giorni full-time

### v0.4.0 close summary (2026-05-21)

15 plan tasks executed across 8 P-groups via kmp-manager:
- P0: T1 (LICENSE MIT) + T7 (dead config removal)
- P1: T2 (explicitApi + BCV 0.16.3 + klib enabled)
- P2: T3 (internal lockdown) + T4 (kotlinx-datetime 0.6.2)
- P3: T5 (writeIndex Long) + T8 (hasData boolean flag)
- P4: T6 (RealtimeChart cleanup) + T9 (snapshot thread safety) + T10 (mutableLongStateOf)
- P5: T11 (single snapshot per signal) + T12 (M4 binning)
- P6: T13 (NaN/Inf/backward guards)
- P7: T14 (NumberFormat extract + 38 tests) + T15 (TieredBuffer/LTTB +25 tests)

Test count: 33 → 107 (+74).
ABI: 211/272 → 161/211 LOC (locked, baseline committed).
RenderLoop.kt deleted. Platform.kt + .android.kt + .ios.kt deleted.
0 `!!` assertions in commonMain. 0 `@Suppress` hacks. explicitApi Strict.

Deviations from plan:
- T4 kotlinx-datetime 0.6.2 instead of 0.7.x (Kotlin 2.1.0 compat — 0.7.x needs Kotlin 2.1.20+). Bump deferred to v0.5.0.
- T7 ChartConfig.targetFps NOT removed (would break ABI of data class). Marked @Deprecated, ignored at runtime. Full removal in v0.5.0.
- T11 memory per signal ~1.14 MB (plan estimate was ~760 KB based on pre-bump TOTAL_CAPACITY). Acceptable.
- T13 unknown-signal push no longer bumps dataVersion (was bumping in v0.3.0). Existing test `push_unknownSignal_stillIncrementsDataVersion` replaced with `pushIgnoresUnknownSignalName` per new contract.

---
*STATE.md — Updated after every significant action*