initial commit: ts time series analysis library v0.1.0

- 354 financial and mathematical time-series indicators
- Uniform C11 API with consistent function signatures
- 349 passing tests with -Werror
- Static and shared library builds
- pkg-config integration
- Python bindings
- Fuzzing and sanitizer support
- Security hardening flags

1 files changed, 132 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..fe8a3e2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,132 @@
+# ts — Time Series Analysis Library
+
+C11 library of 354 financial and mathematical time-series indicators.
+
+The library provides 354 indicators covering moving averages, oscillators,
+volatility measures, statistical functions, and more. See the source files
+in `lib/` for the complete list.
+
+**Requirements:** Any C11-compatible compiler, libm, Python 3 (for code generation).
+
+**Platform:** Little-endian only (x86, x86_64, AArch64). Big-endian is not supported.
+
+**Note:** Generated files (`ts_generated.h`, `lib/ts_flat_generated.c`,
+`lib/ts_registry_generated.c`) are regenerated automatically by the Makefile.
+If you modify indicator sources, run `make` to regenerate.
+
+## Quick Start
+
+```bash
+make          # Build example binary
+make test     # Run all tests
+make lib      # Build static library (libts.a)
+make shared   # Build shared library (libts.so)
+make install  # Install to /usr/local (PREFIX overrideable)
+make check    # Clean build with -Werror + tests
+make sanitize-test  # ASAN + UBSan
+make uninstall # Remove installed files
+```
+
+## Usage
+
+```c
+#define TS_IMPLEMENTATION
+#include "ts.h"
+
+// Types: fp_t == double, ts_uint_t == uint64_t
+
+// Simple moving average (period=10)
+uint_t period = 10;
+fp_t input[100];
+ts_fill(input, 100, 0, 100);  // fill with 0..100
+fp_t output[100];
+fp_t * const y[1] = { output };
+fp_t const * const x[1] = { input };
+
+ts_constant_t c;
+memset(&c, 0, sizeof(c));
+*(uint_t *)c.data = period;
+
+int ret = ts_average(y, 1, x, 1, 100, &c);
+if (ret == -1) { /* error: invalid params or insufficient data */ }
+
+// Valid output starts at index ts_average_offset(&c) == period - 1
+uint_t offset = ts_average_offset(&c);
+for (uint_t i = offset; i < 100; i++) {
+    // output[i] contains valid SMA values
+}
+```
+
+## API
+
+Every indicator shares the same signature:
+
+```c
+int ts_<name>(
+    fp_t * const *y,        // output arrays
+    uint_t y_n,             // number of output arrays
+    fp_t const * const *x,  // input arrays
+    uint_t x_n,             // number of input arrays
+    uint_t n,               // number of data points
+    ts_constant_t const *c  // parameters (opaque buffer)
+);
+```
+
+**Return values:** `0` on success, `-1` on error (invalid parameters, insufficient data).
+
+**Offsets:** Each indicator has a `ts_<name>_offset(c)` function. Output values before the offset are undefined. Valid output starts at index `offset`.
+
+**Parameters:** Pass a struct matching the indicator's expected layout. For simple indicators, a raw `uint_t` period works:
+```c
+uint_t k = 14;
+ts_rsi(y, 1, x, 1, n, &k);  // k is read as ts_rsi_params_t{k}
+```
+
+**OHLCV access:** Multi-input functions use macros:
+- `ts_o(x, i)` — open
+- `ts_h(x, i)` — high
+- `ts_l(x, i)` — low
+- `ts_c(x, i)` — close
+- `ts_v(x, i)` — volume
+
+## Thread Safety
+
+The library is **thread-safe for concurrent reads** but has the following constraints:
+
+- Each indicator function is stateless and does not use global mutable state.
+- Multiple threads can safely call different indicator functions simultaneously.
+- The same indicator function can be called from multiple threads as long as each thread uses its own `x`, `y`, and `c` buffers.
+- `ts_constant()` allocates heap memory — `ts_constant_free()` must be called by the owning thread.
+- The function registry (`ts_registry_get`, `ts_fn_name_get`) returns pointers to static read-only data and is thread-safe.
+
+## Building
+
+| Target | Description |
+|--------|-------------|
+| `make` | Build example binary |
+| `make lib` | Static library |
+| `make shared` | Shared library |
+| `make test` | Run test suite |
+| `make test-one TEST=rsi` | Run single test |
+| `make check` | Clean build with `-Werror` + tests |
+| `make valgrind` | Memory leak check |
+| `make sanitize-test` | ASAN + UBSan (requires libasan) |
+| `make clean` | Remove build artifacts |
+| `make distclean` | Remove build + generated files |
+
+## Install
+
+```bash
+make install                  # /usr/local
+make install PREFIX=/opt/ts   # custom prefix
+```
+
+Installs header, static library, shared library, and pkg-config file. Use with:
+
+```bash
+pkg-config --cflags --libs ts
+```
+
+## License
+
+MIT — Copyright (c) 2025-2026 Ethan Werner