Polymarket Engine — Документация

Тема

Документация — Polymarket Engine ​

Last updated: 2026-08-22 (Backtest/replay/runtime simulation/standalone capture сняты; factual live telemetry и order trace сохранены).

Single source of truth для проекта. После перехода на pm-engine docs/target/ — единственное описание системы. Архитектурные решения растворены в SSOT-документах как разделы «Decision rationale» внутри каждого target-файла.

Карта SSOT ​

Архитектура (target/) ​

  • target/event-context.md — единый неизменяемый контекст события от discovery до позиции: zero-copy, ветви стратегий, шардирование и причинные связи.
  • target/engine.md — pm-engine, hexagonal архитектура, единый pipeline orders/positions/signals/events.
  • target/discovery.md — единый Gamma/WS discovery, полный контракт /events/keyset, событийная модель, профили стратегий, шардирование по event_id и переиспользование данных.
  • target/storage.md — целевые таблицы signals/orders/positions/events.
  • target/wire-contract.md — SSE/REST контракт 1:1 с persisted state.
  • target/risk-and-emergency.md — 3 канонических RISK-LIMITS + EMERGENCY-GUARD.
  • target/extension-points.md — Strategy SDK для будущих стратегий поверх стабильного ядра.
  • target/observability.md — три приёмника наблюдений (SQLite / VictoriaMetrics / ClickHouse), правило маршрутизации, что означает пустое значение, гарантия доставки и названные границы.
  • target/pm-engine-components.excalidraw — карта компонентов по SSOT выше (источники → discovery → data plane → стратегия → денежная граница → приёмники) со стадиями EventContext. Производная схема, не источник истины: при расхождении с текстом правится схема. Открывать в Excalidraw или на холсте mcp-excalidraw-server import.
  • target/event-context.excalidraw — схема к event-context.md: каноническая модель EventContext<Stage>, причинная цепочка стадий с shard(event_id) и fork, разветвление WS после единственного разбора → EventLiveRevision и гарантии доставки, непрерывность книги (AwaitingBaseline ⇄ Ready), хранилища как порты проекций, разрыв «текущее ≠ цель». Производная схема, не источник истины.

ADR (adr/) ​

Активная стратегия (strategies/) ​

  • strategies/README.md — точка входа в раздел.
  • strategies/directional-harvester.md — единственная активная per ADR-024 (PRD + FSD объединены).
  • strategies/take-profit-yield.md — EV-модель относительного take-profit (выход = процент от входа) как альтернатива статической цене Harvester.
  • NegRisk Coverage Band Yield Calculator v2.pdf — актуальная экономическая модель исследуемой конструкции: conditional payout floor по выбранным YES, монетизируемый NO-хедж, финальный Amsterdam ledger и +EV boundary; HTML source. Аналитический reference для архивного multi-arb, не активная стратегия. Предыдущая v1 сохранена как исторический partial-snapshot.
  • strategies/parameters-reference.md — каноническая 5-классовая taxonomy параметров.
  • strategies/regime-market-state-gate.md — режимы рынка (directional.regime, 24 настройки). Механизм скомпилирован, но в бою ВЫКЛЮЧЕН (config.regime=None, подтверждено журналом старта 2026-07-30) и в форму настроек намеренно не выведен. Описание каждой настройки человеческим языком + четыре шага включения.

Интеграции (integrations/) ​

  • integrations/rtds.md — RTDS event stream + toxic-flow detector (config.db directional.toxic_flow knobs).

Операционная документация (operations/) ​

  • operations/runbook.md — единый deploy / smoke / rollback runbook, включая position-limited тестовые итерации через System Restart.
  • deploy/server/README.md — SSOT по VPS: доступ (deploy@poly.grot.app), раскладка каталогов, политика профилей сборки, инварианты (что на сервере лежать не должно), модель угроз. Оперативные команды — в runbook выше; браузерный доступ — CLAUDE.md §Browser access.
  • operations/alerts-and-monitoring.md — pm-engine /metrics (:31340) + in-process AlertEngine → Telegram (внешний Prometheus/Alertmanager стек = future).
  • operations/weather-harvester-analysis-handoff-2026-08-09.md — исторический датированный handoff; его capture/sweep команды сняты и не являются текущей процедурой.
  • operations/trader-observer-runbook.md — Rust read-only накопитель и анализатор публичного поведения jjavi: Data/Gamma/CLOB, синхронные no-action controls, lifecycle, пороговые гипотезы и delta-aware импорт старых capture.
  • operations/design-review-gate.md — SSOT по кросс-модельному ревью замысла: два круга схемы spec-driven-crossreview (требования → решение), формат квитанции и вердикта, слепок против устаревания, что гейт scripts/design-review-gate.sh проверяет и чего он НЕ доказывает, порядок для правок docs/** и openspec/specs/**.
  • operations/local-dashboard-runbook.md — pm-engine-dashboard операторский playbook.
  • operations/rtds-cutover-runbook.md — RTDS toxic-flow активация.
  • operations/rank-exit-migration-runbook.md — активный backup-first cutover с legacy probability-rank V1 на canonical first-breach V2; исторический переход с d_fav сохранён отдельным legacy-разделом.
  • operations/strategy-config-v3-migration-runbook.md — безопасный backup-first cutover config.db v2→v3, rehearsal, version-pinned smoke и парный rollback DB+binary.
  • operations/env-reference.md — переменные окружения по группам.
  • operations/rate-limits.md — канонические CLOB / Gamma / Data лимиты.
  • operations/hot-path-performance-audit-2026-08-14.md — аналитический аудит узких мест на горячих путях pm-engine (путь заявки, запись улик/SQLite, пользовательский канал, периодические задачи, цикл оценки стратегии); НЕ спецификация изменения, решение по мерам — за оператором.
  • operations/contributing-templates.md — шаблоны-заполнители к CONTRIBUTING.md (design, задача, отчёт).
  • operations/harvester-v1-roadmap.md — план-of-record Harvester v1 до измеримого вердикта о доходности; офлайн-бэктест снят, проверка идёт на живых сессиях.
  • operations/harvester-v1-validation-plan.md — исторический план валидации перед длинным запуском; replay/SimOrderClient/capture отменены 2026-08-22.
  • operations/incident-2026-07-14-stop-contour-losses.md — расследование live-потерь −$12.65 (отказ стоп-контура + adverse selection), завершено 2026-07-14.
  • operations/incident-2026-07-15-stop-whipsaw-losses.md — расследование стоп-каскада (3 whipsaw из 4 стопов), план исправлений одобрен 2026-07-17.
  • operations/release-readiness-2026-08-18.md — записка о выкате 2026-08-18 (закрыта): артефакты, схема config.db, набор отката.
  • operations/weather-selection-forward-test.md — исторический pre-registered протокол форвард-теста weather-selection (Ф2); контракт superseded 2026-08-01.
  • history/tech-debt-backlog-2026-08-31.md — tech-debt backlog, снимок на момент архивации (immutable).
  • scripts/analysis/README.md — SSOT по форензике торговли: единая поверхность scripts/analysis/forensics.sh <подкоманда> (ab-state, positions, stops, stop-counterfactual, liquidity-profile, entry-dip, event-dip-lifecycle, ground-truth, ev, unrealized, dust-exposure, rejected-sweep, config-report; полный список всегда даёт forensics.sh --help), их инварианты, ворота достаточности и границы обоснованности выборок. event-dip-lifecycle анализирует wallet-independent bounded public event tape локально и не касается VPS; остальные live-границы описаны в README. Ad-hoc разбор торговых данных вместо этих подкоманд запрещён; вызов — через skill trade-forensics.
  • history/tech-debt-resolved.md — RESOLVED + ARCHIVED-BY-024 + Superseded TDs (immutable snapshot).
  • history/claude-artifacts-2026-09.md — заморозка семи визуальных артефактов claude.ai (сентябрь 2026): чем каждый заменён на сайте документации либо почему не переносится, условие снятия scripts/roadmap-artifact-chips.sh.

Исследования и evidence (analysis/) ​

  • analysis/fill-accounting-survey-2026-09-15.md — замер всей логики учёта исполнения заявок (филлов): пять денежных путей apply_fill_delta, идентичность и high-water-знаки, рестарт/восстановление, прецеденты, действующие SHALL, тесты и открытые вопросы — основание будущей карточки целостного решения (задача 12 durable-cancel-fill-resolution остановлена оператором 2026-09-15).
  • analysis/harvester-engine-session-2026-09-14-postmortem.md — разбор сессии 11–14 сентября: финансовый результат, частичные исполнения, стоп и выходы по рангу, дефекты аналитики и варианты улучшений; границы доказательности указаны в отчёте.
  • analysis/amsterdam-2026-08-15-event-dip-lifecycle.md — wallet-independent жизненный цикл 96 low-price эпизодов Amsterdam (95 YES + 1 NO): baseline/drawdown/recovery, all matched volume, SELL-taker flow как upper bound потенциального maker-выкупа и воспроизводимый JSON.
  • analysis/jjavi-amsterdam-2026-08-15-evidence.md — end-to-end event-ledger Amsterdam 15 August для jjavi: 149 fills, полный maker/taker tape, 11 price histories, conditional payout floor 21–24°C, монетизированный NO26 hedge, terminal payoff при 23°C и границы observed/inferred/not observable.
  • analysis/harvester-engine-session-backup-2026-08-16.md — финальный pre-reset SQLite snapshot production-сессии harvester-engine после завершения всех позиций: provenance, контрольные суммы, покрытие таблиц, offline-команды штатной форензики и границы доказательности.
  • analysis/capture-smoke-2026-08-08.md — исторический замер удалённого standalone recorder; не текущая поверхность и не улика доходности.
  • analysis/harvester-engine-session-2026-08-12-postmortem.md — разбор торговой сессии harvester-engine 12–16 августа 2026; офлайн-часть по неизменяемой копии, границы доказательности указаны в отчёте.
  • analysis/harvester-engine-first-session-after-tick-grid-2026-08-21.md — снимок улик за первые семь часов торговли после снятия дрейна; наблюдения без вывода о доходности (выборка две позиции).

Restoration backlog (restoration-backlog/) ​

Архивные стратегии, удалённые из активного кода per ADR-024. Содержат накопленное знание для будущего восстановления как extension-layer поверх стабильного ядра.

  • restoration-backlog/README.md — единый сводный документ: taxonomy + 7 архивных стратегий (binary-arb, bucket-arb, maker, maker-rebate, paired-maker-rebate, merge-arb, single-token-mm) + условия restoration. Якорные ссылки: #binary-arb, #bucket-arb, #maker, #maker-rebate, #paired-maker-rebate, #merge-arb, #single-token-mm.

Specs и исторические test matrices (specs/) ​

Architecture (вспомогательные, architecture/) ​

  • architecture/polymarket-data-model.md — facts-only data model Polymarket; §8 — контракт отправки заявки (форма отказа, резерв баланса под открытыми заявками, окно задержки, идентификатор заявки = подписной EIP-712-хеш).
  • architecture/polymarket-clob-order-api.md — контракт ответов CLOB на заявку (200 на отказ, errorMsg, delayed / seconds_delay, лента сделок).
  • architecture/directional-test-coverage.md — исторический снимок тестовой архитектуры directional/Harvester; replay/runtime-simulation/standalone-capture из него больше не действуют, актуальные контракты — в openspec/specs/.

Extension-points и pipeline SSOT — target/extension-points.md и target/engine.md.

Исторические test-аудиты (tests/) ​

История (immutable, history/) ​

  • history/INDEX.md — карта snapshot'ов прошлых спринтов и инцидентов.

Crate documentation ​

Workspace содержит 9 CORE крейтов. Крейты pm-bot / pm-dashboard удалены 2026-07-22 после перехода на pm-engine.

  • pm-sdk (crates/pm-sdk/README.md) — canonical Polymarket SDK.
  • pm-common (crates/pm-common/README.md) — shared types + resilience + timezone helpers.
  • pm-engine (crates/pm-engine/) — боевой торговый движок (directional, hexagonal).
  • pm-engine-dashboard (crates/pm-engine-dashboard/README.md) — единственный web dashboard (:31337) + engine SSE proxy.
  • pm-bot-events (crates/pm-bot-events/README.md) — wire contract pm-engine ↔ pm-engine-dashboard.
  • pm-observer (crates/pm-observer/) — read-only наблюдатель публичного поведения внешнего счёта (бинарь pm-trader-observer).
  • pm-cli (crates/pm-cli/README.md) — wallet + strategy setup CLI.
  • pm-analytics (crates/pm-analytics/README.md) — Harvester EV oracle (harvester-ev CLI).

Memory anchors (для агентов) ​

  • ~/.claude/projects/-home-me-RustroverProjects-polymarket-engine/memory/project_canonical_vision.md — A1..A10 + RULE-NEW-01.
  • ~/.claude/projects/-home-me-RustroverProjects-polymarket-engine/memory/project_canonical_risk_limits.md — 3 канонических RISK-LIMITS (доли на рынок / сумма на рынок / общий бюджет).

OpenSpec ​

Активные карточки в openspec/changes/ — ровно две, их реализация продолжается под контролем оператора: gamma-keyset-pagination, event-cohort-rank-freshness. Всё остальное (архив карточек и главные спеки) перенесено 2026-08-31 байт-в-байт в history/openspec/{changes,specs}/ для последующей дистилляции важного в SSOT. Порядок работ — openspec/ROADMAP.md; контроль правок документации — строка в CHANGELOG.md (см. корень).

Env config ​

Все .env* живут под env/ — канонический референс env/.env.example. Активный preset: env/.env.harvester. Strategy knobs хранятся в config.db per ADR-015 — env-файлы несут только infra (RPC, paths, labels).