feat(paper-equities): the equities paper profile — tracked config, venue selection, deployment artifacts, runbook (#370 B2)

[eaitbrahim]

What

Phase B2 of #370 (PRD docs/superpowers/specs/2026-08-18-keel-broker-alpaca-prd.md, Phase B / §5, FR-9/FR-10 posture): the equities paper profile — keel's daily turtle rules on US equities via Alpaca's PAPER API, on their own database, accruing hash-chained paper evidence end-to-end — plus the minimal engine wiring it needs: config-driven venue selection.

The profile (tracked, mirrors the paper-hourly pattern)

• config.paper-equities.yaml — broker: {name: alpaca, endpoint: paper, data_feed: iex}; market_data.granularities is ONE_DAY only (a daily clock — hourly bars exist only within sessions and daily rules do not read them; stated in comments); interval_sec: 86400; weights sum to exactly 1.000; risk_pct: 0.01; caps mirroring the paper profiles; the paper-hourly-style honesty caveat in the header.
• Deployment artifacts — com.keel.paper-equities.plist (strict-XML validated; schedule below), paper-equities-run.sh (UTC-day stamp, set -e, stamp only after a successful cycle, session-window guard), keel-equities wrapper (config + keel-equities.db travel as a pair).
• Runbook — docs/operator-runbook.md gains "The equities paper profile": why it exists (evidence on a session-bound venue; the same honest no-edge caveat), bootstrap (Alpaca paper account, env vars, keel migrate --db keel-equities.db, rules add --kind turtle_breakout --product SYMBOL --params '{"granularity": "ONE_DAY"}' + rules promote --force with the documented bypass rationale, fetch warm — B1 makes weekends quiet), the fourth profile-comparison column, attestation semantics (operator-supplied per (alpaca, SYMBOL), AAOIFI/IFSB-class sources per the fiqh source review; the engine never classifies), rail 17 as ACATS transfer-out, the T+1 × daily-cadence interaction (immaterial for entries; exits never spend), and the two operator-verified opt-outs (stock lending OFF — qabd; high-yield sweep OFF — riba; where to verify each in the Alpaca dashboard). .env.example wires the new key names.

Venue selection (the engine half)

A new broker: config section — name (→ keel.brokers entry-point discovery), endpoint (paper|live), data_feed (iex|sip), both validated at load — threaded through the one broker-construction seam every CLI/agent/TUI path shares (keel/commands/_common.py::_build_broker), plus telemetry's bind_venue in _load_cfg. Secrets follow the CDP pattern: load_alpaca_secrets reads ALPACA_API_KEY_ID/ALPACA_API_SECRET_KEY from the environment or .env; the missing-keys error names the venue and both variables.

When the section is absent, the Coinbase construction path is byte-compatible — pinned by a test that drives the real _build_broker against monkeypatched RESTClient/CoinbaseClient and asserts the exact kwargs — and every pre-existing test stays green unchanged. The config golden baseline is regenerated deliberately (its own documented step) for the new field.

The candidate set — PAPER CANDIDATES

MSFT, AAPL, GOOGL, NVDA, COST — chosen for liquidity (deep daily books, long split-adjusted history, IEX data quality on mega-caps) and as the kind of low-debt large cap a screen could be run on, flat 20% each (flatness states no view). Classification is operator-attested per (alpaca, SYMBOL) before any live consideration; the engine never classifies and this file asserts nothing religiously. There is NO PROVEN EDGE on any asset class; the profile exists for evidence, not profit.

Schedule — a deliberate deviation, stated

The plist fires 10:00–15:00 local (ET), inside the US regular session — not ~30–60 min after the 16:00 ET close. Reason: B1's session gate (#385) skips the whole cycle whenever the venue clock answers closed, so an after-close trigger would log market_closed and never evaluate a bar — zero evidence, forever. The daily bar that closes at 16:00 ET is evaluated at the next session's open (signal on close, execute next open — the conventional daily-system semantics). The runner's window guard (local hours 10–15) keeps a pre-open/after-close closed-market skip (which exits 0) from being stamped as the day's work. DST: the host's zone is America/New_York, so fixed local triggers keep their ET meaning across both US transitions (what moves is the UTC instant, never the distance from the open); the caveat for other hosts is in the plist comment and the runbook.

Deliberately NOT here

• keel/assets screening venue semantics stay hardcoded to coinbase (that hardcoding is deliberate, Venue visibility must be capability-based, not key-presence-based — a read-only key looks identical to a working one #233 live-path work; recorded as the runbook's open item — equity classifications live in the operator's records, the profile trades unattested paper candidates).
• Deployment to the operator's machine (needs their Alpaca paper credentials — the runbook documents the bootstrap).
• Phase C cost fidelity + DCA benchmark.
• No strategy changes — the rules run as-is on equity candles.

Test-first + gates

tests/test_paper_equities_profile.py (35 tests) was written red first — config/broker parsing, alpaca construction, missing-secrets error, plist strict-parse + triggers, the runner harness (real script, date shim, stubbed keel) including the pre-open/after-close stamp regressions, wrapper, runbook pins — then drove the implementation. The byte-compat default pin passed before and after, as a pin should.

• uv run pytest -q — 3225 passed, 2 skipped (both pre-existing expected skips)
• uv run ruff check keel tests packages — clean
• uv run mypy — clean (250 files)

Refs #370 (Phase C continues — not a fix)