docs: runnable quick start; pinned 0.1.12 and opt-in 1.0.0 runtimes; in-process ABI limit

[luisleo526]

Summary

Documentation and package metadata text only: no code, test or version change. The quick start runs as written again, and the docs say which runtimes and engines the harness supports.

• Quick start. Kraken serves only its latest 720 candles, so the README's July 2025 Kraken request returned no bars: step 2 raised IndexError and step 3 exited 1. The examples in the README, getting-started, backtesting and CCXT pages now use bitstamp. The example strategy sizes 10% of equity instead of an unfunded 1 BTC, whose 90 trades all had zero PnL on the pinned runtime.
• Runtimes. The docs name the pinned default, pineforge-release 0.1.12 (engine 0.11.0, codegen 0.9.0). They now say how to run release 1.0.0 (engine 1.0.0, codegen 1.0.0), pinned by digest, in the CLI and in the server image, and that results differ between the two.
• In-process runner. docs/api/backtesting.md states that PineForgeBacktestRunner accepts only PineForge C ABI 2, which engine v0.10.2 through v0.12.3 build. It refuses v0.13.x and v1.0.0 libraries.
• Other corrections:
  • no macro provider ships, so the description, keywords and site description drop "macro";
  • the SQLAlchemy extra needs a database driver;
  • contract-term validation, sub-millisecond timestamp handling and the server cache default in the image are restated;
  • the warmup envelope example now carries the correct first-bar values and the strategy block;
  • a CSV example that raised SchemaMappingError is removed;
  • the fixture notes give the size in MiB and the market-data source.

Verification

This revision (c244330) on Linux arm64, with the README steps taken verbatim from this branch:

Check	Result
pytest	104 passed, 3 skipped
Step 2	exit 0; prints the bitstamp bar timestamp_ms=1751413500000 … close=105709.0
Step 3, pinned default 0.1.12	exit 0; runtime engine 0.11.0, codegen 0.9.0; 88 trades, all with nonzero PnL, none same-bar; 772 equity points
Step 3 with --runtime-image pineforge-release:1.0.0@sha256:b271873d…	exit 0; same top-level keys; runtime engine 1.0.0, codegen 1.0.0; 89 trades, all with nonzero PnL, none same-bar; 772 equity points
DockerBacktestRuntime(image=1.0.0)	the docker-test fixture runs (24 of 24 bars)
Server image built on the 1.0.0 base	ready; concurrent requests served; compile cache reused (one miss, two hits)
PineForgeBacktestRunner.load(<v1.0.0 strategy.so>)	EngineBacktestError: PineForge ABI mismatch: strategy reports 4, expected 2
mkdocs build --strict	exit 0

Added URLs return HTTP 200, and relative links in the changed files resolve. CI's twine check --strict step will likely fail on this PR: twine<7 rejects the Metadata-Version 2.5 that hatchling 1.32 and later write. That predates this PR.

Needed for engine 1.0 (not in this PR)

1. In-process runner on ABI 4 (src/pineforge_data/backtest.py):

   • set EXPECTED_PF_ABI to 4 (line 21);
   • append open_at_end (int32) to _PfTrade;
   • keep or rename sharpe_tv and sortino_tv in _PfEquityStats: v1.0.0 renamed the C fields sharpe_monthly and sortino_monthly at the same offsets, and its release report keeps the old keys, so a rename here changes this report's JSON keys;
   • append broker_state_hash (uint64_t*) and broker_state_hash_len (int64_t) to _PfReport;
   • note that pf_trade_t.max_runup and max_drawdown now hold whole-trade excursions in account currency, not per-unit price travel.

   pf_bar_t and pf_trade_tick_t are unchanged from engine v0.11.0 to v1.0.0.

2. Default runtime. If 1.0.0 should become the default, move the pin in release_contract.py:14-17, the docker/server.Dockerfile:3 default, the assertions at tests/test_docker_integration.py:64 and tests/test_docker_runtime.py:18, and the 0.1.12 trace-collection error at release_contract.py:91, and note the changed results.

Other follow-up

Before the next release, fix the twine>=6.2,<7 pin: it rejects the Metadata-Version 2.5 that hatchling 1.32 and later write.

🤖 Generated with Claude Code