feat: add bounded TQQQ shadow ledger

Introduce a pure, create-only P5 shadow-ledger receipt builder for the frozen TQQQ P2 v5 candidate. It contains no Alpaca client, credentials, network access, broker order payloads, or scheduler. CI is green.

Author: Pigbibi

.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[dev]"
+      - run: ruff check .
+      - run: pytest -q

.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+build/
+dist/
+*.egg-info/

README.md

@@ -1,2 +1,25 @@
 # AlpacaPlatform
+
+QuantStrategyLab 的 Alpaca 执行边界。它分为两个互不混用的阶段：
+
+- P5 `SHADOW`：只生成虚拟账本回执，不连接券商、不读取凭据、不提交订单。
+- P4 `PAPER_DRY_RUN`：未来只会使用独立 paper endpoint 与独立 paper 凭据；不能从 P5 或市场数据配置推断资格。
+
+当前实现仅包含 P5 的 `qsl.tqqq_shadow_cycle_input.v1` 和
+`qsl.tqqq_shadow_ledger_receipt.v1`。每个输入固定候选、策略 revision、P1/P2/P3
+摘要、风险控制摘要与目标权重（basis points）；输出记录相对上一回执的**虚拟**权重变化。
+它不保存市场数据、价格、金额、账户、订单、broker URL 或任何凭据。
+
+P5 receipt 不是 P4/P6 权限。实际调度器只能消费已验签且未过期的独立 P5 policy；P6
+仍由所有者明确决定。
+
+```bash
+python -m alpaca_platform.shadow_ledger --input cycle.json --output receipt.json
+```
+
+输出采用 create-only 写入，避免无意覆盖已有 receipt。运行测试：
+
+```bash
+python -m pytest -q
+```
 Bounded Alpaca paper and shadow execution gateway for QuantStrategyLab

pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "alpaca-platform"
+version = "0.1.0"
+description = "Bounded Alpaca paper and shadow execution gateway for QuantStrategyLab"
+readme = "README.md"
+requires-python = ">=3.11"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.8"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120

src/alpaca_platform/__init__.py

@@ -0,0 +1,15 @@
+"""Bounded P4/P5 execution gateway primitives."""
+
+from .shadow_ledger import (
+    ShadowLedgerError,
+    build_shadow_ledger_receipt,
+    validate_shadow_cycle_input,
+    validate_shadow_ledger_receipt,
+)
+
+__all__ = [
+    "ShadowLedgerError",
+    "build_shadow_ledger_receipt",
+    "validate_shadow_cycle_input",
+    "validate_shadow_ledger_receipt",
+]