mts1b-operations

Compliance, audit chain, halt manager, market-data API. Plus watchdog policy (drift, vpin, news_spike, db_health, position_anomaly, dependency_watchdog, portfolio_vol_dd).

Repo: github.com/MTS1B/mts1b-operations Layer: 4 Wave: 2 (months 4-7) Depends on: foundation, platform, brokers, riskengine Audience: every service publishes events here; operators consume halt + audit views

What it is

The observability + governance surface. Subscribes to every NATS subject, persists audit, enforces halts, and runs ~10 watchdogs that emit alerts when something looks wrong.

Sub-area	What
Audit chain	Merkle-hashed append-only log of every state transition
Halt manager	Per-fund / firm-wide halt with operator co-sign
Watchdogs	10 background runners observing different dimensions of system health
Compliance	Reg-reporting (CAT/OATS/MIFID — v3)
Market-data API	Public read-only API for demos and dashboards

Watchdogs

Watchdog	What it watches	Trigger	Action
`predictive_health`	overall NAV trajectory vs. backtested envelope	NAV outside 99% CI	Telegram warn
`drift_monitor`	live IC vs. backtest IC per strategy	drift_zscore < -1.0	halve allocation
`vpin`	bulk-volume probability of informed trading	VPIN > 0.4	throttle aggressive orders
`news_spike`	sudden news volume on held names	> 5σ vs 30d avg	Telegram + cooldown
`position_anomaly`	unusual position size deltas	δ > 2σ from typical	Telegram
`db_watchdog`	Postgres / DuckDB integrity	row count mismatch, slow queries	alert + auto-vacuum
`strategy_watchdog`	per-strategy P/L vs. expected	rolling 30d outside 95% CI	shadow
`theta_watchdog`	option positions' theta exposure	net theta > X	enforce hedge
`dependency_watchdog`	upstream service health	/healthz red for 3 polls	alert + retry
`portfolio_vol_dd`	realized portfolio vol vs. target	realized > 1.5× target	reduce gross

Each watchdog is configurable per fund via Vault.

Module layout

mts1b_operations/
├── audit/
│   ├── chain.py              # Merkle-hashed log
│   └── verifier.py
├── halt/
│   ├── manager.py
│   └── operator_signoff.py
├── watchdogs/
│   ├── predictive_health.py
│   ├── drift_monitor.py
│   ├── vpin.py
│   ├── news_spike.py
│   ├── position_anomaly.py
│   ├── db_watchdog.py
│   ├── strategy_watchdog.py
│   ├── theta_watchdog.py
│   ├── dependency_watchdog.py
│   └── portfolio_vol_dd.py
├── compliance/
│   ├── audit_export.py        # for regulators
│   └── reg_reporting/         # CAT, OATS, MIFID (v3)
├── api/
│   ├── rest.py                # FastAPI — halt control, audit query, watchdog status
│   ├── grpc.py
│   └── nats.py                # subscribes mts.v1.>
└── workers/
    └── halt_enforcer.py       # acts on HaltRequest events

Halt manager

The kill-switch architecture. Three halt levels:

Level	Scope	How triggered	Reset
`STRATEGY_HALT`	one strategy	drawdown halt OR drift_zscore < -2.0 OR manual	operator `mts cmd resume <strategy_id>`
`FUND_HALT`	one fund	fund daily_loss_halt_pct breached	operator `mts cmd resume <fund_id>`
`FIRM_HALT`	everything	manual or `news_spike` on aggregate	operator co-sign required

Halts publish to mts.v1.operations.halt.requested. mts1b-oms listens and stops accepting matching orders.

mts cmd halt                  # firm-wide HALT (confirmation: type HALT)
mts cmd cancel-all            # cancel every open order (CANCEL)
mts cmd flatten-paper         # flatten every paper fund (FLATTEN)
mts cmd resume                # lift all runtime halts
mts cmd resume <fund_id>      # lift one fund's halt
mts cmd resume <strategy_id>  # lift one strategy's halt

Audit chain

Every state-changing action is logged. The chain is Merkle-hashed for tamper detection:

class AuditEntry(BaseModel):
    sequence: int
    timestamp: datetime
    actor: str
    action: str
    subject_id: str
    data: dict
    prev_hash: str
    hash: str               # sha256(prev_hash + serialize(everything else))

Verify integrity:

mts1b-operations audit verify --from-sequence 0
# ✓ 47832 entries, chain integrity OK, no gaps

Used for: compliance reporting, post-mortem RCA, debugging "why did this order get rejected?"

Market-data API (read-only public)

A small subset of market data exposed via REST/WebSocket for demo dashboards. Read-only, rate-limited, no auth needed for top-level endpoints:

GET /v1/quotes/AAPL          → Quote
GET /v1/bars/AAPL?interval=1d&start=2024-01-01 → list[Bar]
GET /v1/funds                 → list[FundStatus]
GET /v1/halts                 → list[HaltRequest]

Used by mts1b.investmentparadisellc.com landing page for the "live status" widget.

Compliance + reg-reporting (v3)

CAT (Consolidated Audit Trail), OATS (legacy), MIFID-II transaction reporting. Hookable adapters:

from mts1b_operations.compliance.reg_reporting import cat

await cat.report_event(
    event_type="newOrderEvent",
    order=order,
    venue=venue,
    actor=actor,
)
# Writes to per-day CAT submission file; daily upload to FINRA

CAT and OATS are SEC-only and apply only if you're a US broker-dealer. Most MTS1B users don't need these; they're shipped for those who do.

Build + test

pip install -e ".[dev]"
pytest -m unit
docker compose up -d nats postgres
pytest -m integration

Roadmap

Version	Items
0.1 (Wave 2)	Audit chain, halt manager, 10 watchdogs, market-data API
0.2 (Wave 2)	Operator dashboard (consolidated halt + audit view in frontends)
0.3 (Wave 3)	CAT / OATS / MIFID reg-reporting (community-driven)
1.0 (LTS)	Stable halt + audit schemas

What it is​

Watchdogs​

Module layout​

Halt manager​

Audit chain​

Market-data API (read-only public)​

Compliance + reg-reporting (v3)​

Build + test​

Roadmap​

See also​