feat(data-layer): TickAggregator (tick-to-candle) in all 10 languages (#309)

* feat(data-layer): TickAggregator in Node, WASM, Python + C ABI hub

First data-layer feature (F2): roll trade ticks up into fixed-timeframe OHLCV
candles, exposed natively and over the C ABI.

- wickra-data wired as a binding dependency (workspace dep; its wickra-core dep
  is default-features=false so it never forces rayon into the rayon-free WASM
  build — native bindings re-enable parallel through their own dependency).
- Node `TickAggregator(bucket, gapFill?)` -> `push(price, size, ts): Candle[]`;
  WASM the same (array of objects); Python `push(...) -> list[tuple]`.
- C ABI: `WickraCandle` struct + `wickra_tick_aggregator_new/push/free` (push
  writes candles into a caller buffer and returns the count), generated via the
  capi generator's new DATA_LAYER section; cbindgen now parses wickra-data so
  `TickAggregator` is a forward-declared opaque; header vendored to bindings/go.

Verified bit-identical across Node/WASM/Python/C/C++ (o=100 h=101 l=100 c=101
v=3 ts=0 for the shared 3-tick probe). WIP: Go/C#/Java/R generated bindings and
the cross-language golden are still pending.

* feat(data-layer): TickAggregator in Go, C#, Java, R (lossless push/drain)

Complete F2 across all 10 languages: the C-ABI tick aggregator now uses a
two-step push/drain so gap-fill candles are never lost, and the four generated
bindings expose it idiomatically.

- C ABI redesigned: opaque TickAggregator handle (inner aggregator + pending
  buffer); push consumes a tick and returns the closed-candle count, drain copies
  them into a count-sized caller buffer.
- Go: NewTickAggregator + Push(price,size,ts) []Candle; C#: TickAggregator +
  Candle[] Push(...); Java: TickAggregator + Candle[] push(...); R: TickAggregator
  constructor + push() S3 generic returning an (n x 6) numeric matrix.
- Candle output record generated per language from WickraCandle.

Verified bit-identical to the native bindings (o=100 h=101 l=100 c=101 v=3 ts=0)
in Go, C#, Java, and R at runtime; R passes R CMD check (pre-existing doc
warnings only). WIP: cross-language data-layer golden + CHANGELOG still pending.

* test(data-layer): cross-language golden for the tick aggregator + CHANGELOG

gen_golden emits a deterministic tick stream (testdata/golden/data_ticks.csv) and
the reference candle streams with and without gap filling (data_candles.csv,
data_candles_gap.csv). Every binding replays the shared ticks through its
TickAggregator and checks the candles bit-for-bit (fp tolerance) against the Rust
reference:

- Node / WASM / Python / Go / C# / Java / R: a dedicated parity test each.
- C / C++: data_layer_test.c (compiled as both, run as ctest).

The gap-fill fixture closes several candles from a single push, exercising the
lossless push/drain path. Records the feature under CHANGELOG [Unreleased].

* fix(examples): rename the CSV-loader candle to WickraBar

The example CSV helper (wickra_csv.h) defined its own struct WickraCandle, which
now collides with the public C ABI WickraCandle (the tick aggregator output) in
any example that includes both headers (backtest, multi_timeframe, the strategy
examples). The public type owns the name; rename the example loader's bar to
WickraBar. The generated golden_test.c is untouched (its only match was the
unrelated WickraCandleVolumeOutput).

examples/c/CMakeLists.txt

@@ -83,7 +83,8 @@ endif()
 # prove the C ABI header is consumable from each language. The fixtures live at
 # the repo root; pass the absolute path as the test argument.
 get_filename_component(WICKRA_GOLDEN_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../testdata/golden" ABSOLUTE)
-foreach(gt_pair "golden_test:golden_test.c" "golden_test_cpp:golden_test.cpp")
+foreach(gt_pair "golden_test:golden_test.c" "golden_test_cpp:golden_test.cpp"
+                "data_layer_test:data_layer_test.c" "data_layer_test_cpp:data_layer_test.cpp")
     string(REPLACE ":" ";" gt_list "${gt_pair}")
     list(GET gt_list 0 gt_name)
     list(GET gt_list 1 gt_src)

examples/c/backtest.c

@@ -34,7 +34,7 @@ static double last_finite(const double *v, size_t n) {
 int main(int argc, char **argv) {
     const char *path = (argc > 1) ? argv[1] : WICKRA_DATA_DIR "/btcusdt-1d.csv";
 
-    WickraCandle *candles = NULL;
+    WickraBar *candles = NULL;
     size_t n = wickra_load_csv(path, &candles);
     if (n == 0) {
         fprintf(stderr, "backtest: no candles read from %s\n", path);
@@ -77,7 +77,7 @@ int main(int argc, char **argv) {
     double last_atr = NAN;
     double last_obv = NAN;
     for (size_t i = 0; i < n; ++i) {
-        const WickraCandle *c = &candles[i];
+        const WickraBar *c = &candles[i];
         WickraBollingerOutput bo;
         if (wickra_bollinger_bands_update(bb, c->close, &bo)) {
             last_bb = bo;

examples/c/data_layer_test.c

@@ -0,0 +1,107 @@
+/* Cross-language data-layer parity for the C / C++ binding: replay the shared
+ * golden tick stream through the TickAggregator (push/drain) and check the
+ * candles against the Rust reference, with and without gap filling. The same
+ * source compiles under both a C and a C++ compiler. Fixtures are generated by
+ * `cargo run -p wickra-examples --bin gen_golden`; the golden dir is argv[1].
+ */
+#include <math.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include "wickra.h"
+
+#define MAXROWS 256
+
+static const char *GDIR;
+
+static int read_csv(const char *name, double *rows, int ncol) {
+    char path[1024];
+    snprintf(path, sizeof(path), "%s/%s.csv", GDIR, name);
+    FILE *f = fopen(path, "r");
+    if (!f) {
+        fprintf(stderr, "cannot open %s\n", path);
+        exit(2);
+    }
+    char line[4096];
+    int n = 0, first = 1;
+    while (fgets(line, sizeof(line), f)) {
+        line[strcspn(line, "\r\n")] = '\0';
+        if (first) {
+            first = 0;
+            continue;
+        }
+        if (line[0] == '\0') {
+            continue;
+        }
+        char *p = line;
+        for (int j = 0; j < ncol; j++) {
+            rows[n * ncol + j] = strtod(p, &p);
+            if (*p == ',') {
+                p++;
+            }
+        }
+        n++;
+    }
+    fclose(f);
+    return n;
+}
+
+static int check(const char *fixture, bool gap, const double *ticks, int nt) {
+    struct TickAggregator *a = wickra_tick_aggregator_new(1000, gap);
+    if (!a) {
+        printf("FAIL %s: new returned NULL\n", fixture);
+        return 1;
+    }
+    double want[MAXROWS * 6];
+    int nw = read_csv(fixture, want, 6);
+    double got[MAXROWS * 6];
+    int ng = 0;
+    for (int i = 0; i < nt; i++) {
+        intptr_t n = wickra_tick_aggregator_push(a, ticks[i * 3 + 0], ticks[i * 3 + 1],
+                                                 (int64_t)ticks[i * 3 + 2]);
+        if (n > 0) {
+            struct WickraCandle buf[MAXROWS];
+            intptr_t w = wickra_tick_aggregator_drain(a, buf, (uintptr_t)n);
+            for (intptr_t j = 0; j < w; j++) {
+                got[ng * 6 + 0] = buf[j].open;
+                got[ng * 6 + 1] = buf[j].high;
+                got[ng * 6 + 2] = buf[j].low;
+                got[ng * 6 + 3] = buf[j].close;
+                got[ng * 6 + 4] = buf[j].volume;
+                got[ng * 6 + 5] = (double)buf[j].timestamp;
+                ng++;
+            }
+        }
+    }
+    wickra_tick_aggregator_free(a);
+    if (ng != nw) {
+        printf("FAIL %s: %d candles vs %d\n", fixture, ng, nw);
+        return 1;
+    }
+    int fails = 0;
+    for (int i = 0; i < ng; i++) {
+        for (int j = 0; j < 6; j++) {
+            double w = want[i * 6 + j];
+            double tol = 1e-9 * fmax(1.0, fabs(w));
+            if (fabs(got[i * 6 + j] - w) > tol) {
+                printf("FAIL %s row %d col %d: %g vs %g\n", fixture, i, j, got[i * 6 + j], w);
+                fails++;
+            }
+        }
+    }
+    return fails;
+}
+
+int main(int argc, char **argv) {
+    GDIR = (argc > 1) ? argv[1] : "testdata/golden";
+    double ticks[MAXROWS * 3];
+    int nt = read_csv("data_ticks", ticks, 3);
+    int fails = check("data_candles", false, ticks, nt);
+    fails += check("data_candles_gap", true, ticks, nt);
+    if (fails == 0) {
+        printf("C/C++ data layer: OK (%d ticks)\n", nt);
+    }
+    return fails ? 1 : 0;
+}

examples/c/data_layer_test.cpp

@@ -0,0 +1,3 @@
+/* C++ build of the data-layer parity test: the C ABI header is `extern "C"`, so
+ * the exact same source compiles under a C++ compiler too. */
+#include "data_layer_test.c"

examples/c/multi_timeframe.c

@@ -30,12 +30,12 @@
 /* Aggregate `in` into fixed-width time buckets of `tf_ms`. Writes the bucketed
  * candles into the caller-owned `out` (capacity >= count) and returns how many
  * buckets were produced. */
-static size_t resample(const WickraCandle *in, size_t count, int64_t tf_ms,
-                       WickraCandle *out) {
+static size_t resample(const WickraBar *in, size_t count, int64_t tf_ms,
+                       WickraBar *out) {
     size_t produced = 0;
     int open_bucket = 0;
     int64_t bucket_start = 0;
-    WickraCandle cur = {0};
+    WickraBar cur = {0};
     for (size_t i = 0; i < count; ++i) {
         int64_t b = in[i].timestamp - (in[i].timestamp % tf_ms);
         if (!open_bucket || b != bucket_start) {
@@ -63,7 +63,7 @@ static size_t resample(const WickraCandle *in, size_t count, int64_t tf_ms,
     return produced;
 }
 
-static void summarize(const char *label, const WickraCandle *candles, size_t n) {
+static void summarize(const char *label, const WickraBar *candles, size_t n) {
     if (n == 0) {
         printf("  %-5s (empty)\n", label);
         return;
@@ -76,7 +76,7 @@ static void summarize(const char *label, const WickraCandle *candles, size_t n)
     double last_hist = NAN;
     double last_adx = NAN;
     for (size_t i = 0; i < n; ++i) {
-        const WickraCandle *c = &candles[i];
+        const WickraBar *c = &candles[i];
         double r = wickra_rsi_update(rsi, c->close);
         if (isfinite(r)) {
             last_rsi = r;
@@ -119,14 +119,14 @@ static void summarize(const char *label, const WickraCandle *candles, size_t n)
 int main(int argc, char **argv) {
     const char *path = (argc > 1) ? argv[1] : WICKRA_DATA_DIR "/btcusdt-1m.csv";
 
-    WickraCandle *ones = NULL;
+    WickraBar *ones = NULL;
     size_t n = wickra_load_csv(path, &ones);
     if (n == 0) {
         fprintf(stderr, "multi_timeframe: no candles read from %s\n", path);
         return 1;
     }
     /* Resampling only ever produces fewer candles than the 1m source. */
-    WickraCandle *buf = (WickraCandle *)malloc(n * sizeof(*buf));
+    WickraBar *buf = (WickraBar *)malloc(n * sizeof(*buf));
     if (buf == NULL) {
         fprintf(stderr, "multi_timeframe: allocation failed\n");
         free(ones);

examples/c/strategy_bollinger_squeeze.c

@@ -37,7 +37,7 @@
 int main(int argc, char **argv) {
     const char *path = (argc > 1) ? argv[1] : WICKRA_DATA_DIR "/btcusdt-1d.csv";
 
-    WickraCandle *candles = NULL;
+    WickraBar *candles = NULL;
     size_t n = wickra_load_csv(path, &candles);
     if (n < SQUEEZE_LOOKBACK + BB_PERIOD) {
         fprintf(stderr, "dataset has only %llu bars; need at least %d\n",
@@ -64,7 +64,7 @@ int main(int argc, char **argv) {
     double equity = 1.0;
 
     for (size_t i = 0; i < n; ++i) {
-        const WickraCandle *c = &candles[i];
+        const WickraBar *c = &candles[i];
         double price = c->close;
         WickraBollingerOutput b;
         int bb_ready = wickra_bollinger_bands_update(bb, price, &b);

examples/c/strategy_macd_adx.c

@@ -34,7 +34,7 @@
 int main(int argc, char **argv) {
     const char *path = (argc > 1) ? argv[1] : WICKRA_DATA_DIR "/btcusdt-1h.csv";
 
-    WickraCandle *candles = NULL;
+    WickraBar *candles = NULL;
     size_t n = wickra_load_csv(path, &candles);
     if (n == 0) {
         fprintf(stderr, "CSV is empty: %s\n", path);
@@ -58,7 +58,7 @@ int main(int argc, char **argv) {
     int prev_hist_sign = -1;
 
     for (size_t i = 0; i < n; ++i) {
-        const WickraCandle *c = &candles[i];
+        const WickraBar *c = &candles[i];
         double price = c->close;
         WickraMacdOutput m;
         int macd_ready = wickra_macd_indicator_update(macd, price, &m);

examples/c/strategy_rsi_mean_reversion.c

@@ -34,7 +34,7 @@
 int main(int argc, char **argv) {
     const char *path = (argc > 1) ? argv[1] : WICKRA_DATA_DIR "/btcusdt-1h.csv";
 
-    WickraCandle *candles = NULL;
+    WickraBar *candles = NULL;
     size_t n = wickra_load_csv(path, &candles);
     if (n < RSI_PERIOD * 4) {
         fprintf(stderr, "dataset too small: %llu\n", (unsigned long long)n);

examples/c/wickra_csv.h

@@ -15,27 +15,27 @@
 #include <stddef.h>
 #include <stdint.h>
 
-typedef struct WickraCandle {
+typedef struct WickraBar {
     int64_t timestamp;
     double open;
     double high;
     double low;
     double close;
     double volume;
-} WickraCandle;
+} WickraBar;
 
 /* Load an OHLCV CSV into a malloc'd array. Returns the candle count and stores
  * the array in *out (caller frees with free()). Returns 0 and leaves *out NULL
  * on any error (missing file, no parseable rows). A leading header line whose
  * first field is non-numeric is skipped. */
-size_t wickra_load_csv(const char *path, WickraCandle **out);
+size_t wickra_load_csv(const char *path, WickraBar **out);
 
 #ifdef WICKRA_CSV_IMPL
 
 #include <stdio.h>
 #include <stdlib.h>
 
-size_t wickra_load_csv(const char *path, WickraCandle **out) {
+size_t wickra_load_csv(const char *path, WickraBar **out) {
     *out = NULL;
     FILE *f = fopen(path, "r");
     if (f == NULL) {
@@ -45,7 +45,7 @@ size_t wickra_load_csv(const char *path, WickraCandle **out) {
 
     size_t cap = 1024;
     size_t n = 0;
-    WickraCandle *rows = (WickraCandle *)malloc(cap * sizeof(*rows));
+    WickraBar *rows = (WickraBar *)malloc(cap * sizeof(*rows));
     if (rows == NULL) {
         fclose(f);
         return 0;
@@ -53,7 +53,7 @@ size_t wickra_load_csv(const char *path, WickraCandle **out) {
 
     char line[512];
     while (fgets(line, (int)sizeof(line), f) != NULL) {
-        WickraCandle c;
+        WickraBar c;
         long long ts = 0;
         /* sscanf returns the number of fields successfully matched. A header
          * row ("timestamp,...") matches 0 and is skipped. */
@@ -66,7 +66,7 @@ size_t wickra_load_csv(const char *path, WickraCandle **out) {
 
         if (n == cap) {
             cap *= 2;
-            WickraCandle *grown = (WickraCandle *)realloc(rows, cap * sizeof(*rows));
+            WickraBar *grown = (WickraBar *)realloc(rows, cap * sizeof(*rows));
             if (grown == NULL) {
                 free(rows);
                 fclose(f);

examples/rust/src/bin/gen_golden.rs

@@ -17,8 +17,9 @@ use std::path::Path;
 
 use wickra::{
     AdOscillator, Adx, Atr, AverageDrawdown, AwesomeOscillatorHistogram, Beta, Candle, Ema,
-    Indicator, IntradayIntensity, MacdIndicator, Rsi, Sma,
+    Indicator, IntradayIntensity, MacdIndicator, Rsi, Sma, Tick,
 };
+use wickra_data::aggregator::{TickAggregator, Timeframe};
 
 const N: usize = 80;
 
@@ -183,9 +184,52 @@ fn main() {
     emit_special(dir, &candles);
     emit_profiles(dir, &candles);
     emit_bars(dir, &candles);
+    emit_data_layer(dir);
     println!("golden fixtures written to {}", dir.display());
 }
 
+/// Deterministic trade tick `i`: price on the shared varied path, a small
+/// repeating size, and a timestamp that places roughly three ticks per
+/// 1000-unit bucket. A deliberate jump at `i == 36` opens a multi-bucket gap so
+/// the gap-fill fixture exercises several flat candles emitted from one push.
+fn tick(i: usize) -> (f64, f64, i64) {
+    let t = i as f64;
+    let price = 100.0 + 10.0 * (t * 0.3).sin() + 0.5 * t;
+    let size = 1.0 + (i % 5) as f64;
+    let base = i64::try_from(i).expect("tick index fits i64") * 350;
+    let ts = if i >= 36 { base + 5000 } else { base };
+    (price, size, ts)
+}
+
+/// Data layer: the tick-to-candle aggregator. Writes the shared tick input plus
+/// the reference candle streams with and without gap filling.
+fn emit_data_layer(dir: &Path) {
+    const N_TICKS: usize = 60;
+    let ticks: Vec<(f64, f64, i64)> = (0..N_TICKS).map(tick).collect();
+
+    let mut tin = Vec::with_capacity(N_TICKS);
+    for &(price, size, ts) in &ticks {
+        tin.push(format!("{price},{size},{ts}"));
+    }
+    write_csv(dir, "data_ticks", "price,size,timestamp", &tin);
+
+    let header = "open,high,low,close,volume,timestamp";
+    for (name, gap_fill) in [("data_candles", false), ("data_candles_gap", true)] {
+        let mut agg = TickAggregator::new(Timeframe::new(1000).unwrap()).with_gap_fill(gap_fill);
+        let mut rows = Vec::new();
+        for &(price, size, ts) in &ticks {
+            let tick = Tick::new(price, size, ts).expect("valid tick");
+            for c in agg.push(tick).expect("valid push") {
+                rows.push(format!(
+                    "{},{},{},{},{},{}",
+                    c.open, c.high, c.low, c.close, c.volume, c.timestamp
+                ));
+            }
+        }
+        write_csv(dir, name, header, &rows);
+    }
+}
+
 // AUTO-GENERATED scalar-output golden tranche (single f64 output).
 #[allow(clippy::too_many_lines)]
 fn emit_scalar(dir: &Path, candles: &[Candle], closes: &[f64]) {