# 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: v1.0.0-public-release (IN PROGRESS — autonomous tasks done, user-blocked tasks pending)
Phase: Portfolio prep autonomous batch shipped (debt partial, docs, CI, demos). User-side tasks pending.
Plan: .paul/phases/v1.0.0-public-release-plan.md
Status: 5/10 plan tasks done (T2, T3, T5, T6, T8 partial + T9 perf docs + partial debt). 5 blocked on user (T1 Maven Central, T4 benchmark vs competitors, T7 assets, T10 tag/release, app rename).
Last completed: v1.0.0 portfolio prep autonomous batch (2026-05-22)
Last activity: 2026-05-22 — Autonomous portfolio prep batch. 1 debt warning cleared (klib non-packed compat removed; 8 remain blocked behind com.android.kotlin.multiplatform.library migration). Docs: CHANGELOG.md, CONTRIBUTING.md, chart-realtime/README.md rewrite, docs/PERFORMANCE.md. CI: .github/workflows/{ci,release}.yml + dependabot + PR template + 2 issue templates. Android demo (T8) polished: Material3 control panel (sample rate slider, signal count, waveform per signal, window seconds, LoD picker, axis label mode, formatter picker, interaction toggle, theme switch, status row). iOS SwiftUI demo (T3 scaffold) via SPM Package.swift + sources; xcodebuild builds green; smoke test confirms XCFramework consumable from Swift; ComposeUIViewController shim deferred to v1.0.0 T1.

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
- v0.5.0 milestone: [██████████] 100% SHIPPED
- v1.0.0 milestone: [█████░░░░░] 50% portfolio prep done, user-blocked items pending

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
- v0.5.0 milestone: [██████████] 100% SHIPPED

## Loop Position

```
PLAN ──▶ APPLY ──▶ UNIFY
  ✓        ◐        ✓     [v1.0.0 partial — autonomous batch done, user-blocked items pending]
```

## v1.0.0 deferred (need user)

- **T1 Maven Central publish** — Sonatype OSSRH account + GPG key + DNS TXT proof for `dev.dtrentin` namespace
- **T4 Benchmark vs competitors** — methodology decision (JMH? androidx.benchmark? both?), Maven coords for Vico/KoalaPlot/MPAndroidChart, hardware target (Pixel 6 / iPhone 13 vs CI runners)
- **T7 Logo / banner / GIF** — design assets (manager cannot generate raster/vector art)
- **T10 Tag + release + push to GitHub** — user wants to wait on GitHub (potential project rename). Currently remote = ssh://3nt-git.duckdns.org:222/davide.trentin/KMPCharts.git
- **App rename** — user mentioned considering rename; deferred
- **ComposeUIViewController shim** (T1 dependency) — small Kotlin shim in `chart-realtime/src/iosMain/` exporting `RealtimeChartViewController(state, xWindowSeconds): UIViewController` to enable real SwiftUI demo

## v1.0.0 deferred (out-of-scope debt)

- **Remaining 8 deprecation warnings** (KGP 2.3 / AGP 9 `:app` plugin + `libraryVariants` API + AGP-newDsl) blocked behind migration to `com.android.kotlin.multiplatform.library` 9.2.0. Migration forces ABI baseline regen + restructured Maven publication graph + XCFramework hierarchy expansion. Deferred as dedicated post-1.0.0 ticket.

## 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 (iosX64 dropped in v0.5.0 D1) |
| Drop iosX64 target | v0.5.0 D1 | Compose-MP 1.11.0 no ios_x64 variant; Apple deprecated Intel Mac sims Xcode 15+; iosArm64 + iosSimulatorArm64 cover modern devs |
| 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*