Add schema-mapped local data providers

CONTRIBUTING.md

@@ -34,6 +34,8 @@ docker version
 - Make retries, timeouts, and rate limits explicit.
 - Add offline fixture tests. CI must not require network access or API keys.
 - Declare provider-specific libraries as optional dependencies.
+- Keep local/database adapters read-only, validate mapped identifiers against
+  reflected metadata, and bind query values instead of accepting raw SQL.
 - Keep provider-specific request parameters inside the adapter rather than
   extending the normalized records.
 - Never make `pineforge-engine` depend on this package.

README.md

@@ -23,6 +23,8 @@ the engine receives only normalized bars and ordered trades.
   live trades, macro vintages, and validation rules.
 - [Using providers](docs/providers.md) — registry, CCXT market discovery,
   historical bars, live trades, configuration, and errors.
+- [Local files and databases](docs/local-data.md) — runtime schema discovery,
+  arbitrary CSV/SQLite DDL, SQLAlchemy databases, and column mappings.
 - [Backtesting](docs/backtesting.md) — CLI options, configuration files, runtime
   channels, report schema, and reproducibility.
 - [FastAPI server](docs/server.md) — concurrency, authentication, timeouts,
@@ -50,6 +52,8 @@ into contiguous C ABI arrays and submitted in one call.
   `MacroDataProvider` — small structural protocols that community adapters
   implement.
 - `ProviderRegistry` — built-in and installed broker adapters selected by name.
+- `BarColumnMapping` and `TabularSchema` — runtime discovery and safe OHLCV
+  mappings for user-owned files, tables, and views.
 - `PfBar`, `PfTradeTick`, and `EngineStreamSink` — dependency-free `ctypes`
   interoperability with PineForge strategy libraries.
 
@@ -96,6 +100,40 @@ this bootstrap; a WebSocket transport can implement the same
 after an engine warmup. `start_sequence` is the last accepted sequence, so the
 adapter emits `start_sequence + 1` next.
 
+## Local files and databases
+
+Built-in `csv`, `sqlite`, and `sqlalchemy` providers let users backtest their
+own data without adopting a fixed PineForge DDL. They inspect file headers or
+database reflection metadata at runtime, infer common OHLCV names, and accept
+partial mappings for arbitrary names. Ambiguous schemas fail instead of being
+guessed.
+
+```python
+from pineforge_data import SqliteBarProvider
+
+
+provider = SqliteBarProvider(
+    "warehouse.sqlite3",
+    table="price candles",
+    mapping={
+        "timestamp": "epoch seconds",
+        "open": "first px",
+        "high": "top px",
+        "low": "bottom px",
+        "close": "last px",
+        "volume": "traded qty",
+    },
+    timestamp_unit="seconds",
+)
+schema = await provider.inspect_schema()
+```
+
+SQL identifiers are validated against reflected metadata; filter values are
+bound parameters. For complex transformations, expose a database view rather
+than putting raw SQL in harness configuration. See the complete
+[local-data guide](docs/local-data.md) for CSV, native read-only SQLite,
+SQLAlchemy URLs, timestamp handling, symbol/timeframe semantics, and CLI JSON.
+
 ## Direct backtest harness
 
 The public backtest input is raw PineScript v6. `pineforge-backtest` fetches

docs/backtesting.md

@@ -95,6 +95,12 @@ Pine input overrides:
 Input and override values sent to the FastAPI service must be scalar strings,
 numbers, or booleans.
 
+The same harness accepts `--provider csv`, `--provider sqlite`, or
+`--provider sqlalchemy`. Their provider configuration maps arbitrary source
+columns to normalized OHLCV, while raw Pine and normalized bars follow the
+same local-container or FastAPI path. See
+[Local files and databases](local-data.md) for complete configuration examples.
+
 ## Runtime image policy
 
 The package default is an exact `pineforge-release` version and OCI digest. The

docs/getting-started.md

@@ -24,6 +24,7 @@ Available extras:
 | Extra | Purpose |
 |---|---|
 | `ccxt` | CCXT async exchange adapter |
+| `database` | SQLAlchemy 2.x database reflection and queries |
 | `server` | FastAPI and Uvicorn server dependencies |
 | `dev` | tests, type checking, formatting, and package builds |
 
@@ -103,5 +104,6 @@ cache.
 
 - [Learn the normalized data model](data-model.md).
 - [Search and filter provider markets](providers.md).
+- [Connect local CSV, SQLite, or SQLAlchemy data](local-data.md).
 - [Configure parameters, runtime channels, and reports](backtesting.md).
 - [Deploy the concurrent server](server.md).

docs/index.md

@@ -24,6 +24,7 @@ exchange / broker / macro API
 | Install the package and run a first backtest | [Getting started](getting-started.md) |
 | Understand instruments, contracts, bars, trades, and macro vintages | [Data model](data-model.md) |
 | Discover markets and use CCXT or another provider | [Using providers](providers.md) |
+| Connect a CSV file, SQLite table, or SQLAlchemy database | [Local files and databases](local-data.md) |
 | Configure local and remote raw-Pine backtests | [Backtesting](backtesting.md) |
 | Deploy and operate the concurrent FastAPI service | [FastAPI server](server.md) |
 | Implement a new exchange or broker adapter | [Provider contract](provider-contract.md) |
@@ -46,6 +47,8 @@ exchange / broker / macro API
 - historical bars exclude the currently forming candle when the provider can
   identify it;
 - exact catalog resolution distinguishes spot, swaps, futures, and options;
+- user-owned tabular schemas are reflected and mapped explicitly rather than
+  requiring a PineForge-owned DDL;
 - macro observations retain release and vintage timestamps to avoid revised-
   data lookahead;
 - backtest reports identify both the resolved market and runtime versions.