pandora-cli-skills 1.1.43 → 1.1.45

package/README.md

@@ -130,6 +130,25 @@ pandora --output json lifecycle resolve --id <lifecycle-id> --confirm
 - `pandora schema`
 - `pandora mcp`
 
+## Quant ABM Baseline (Module Contract)
+
+- Deterministic ABM engine: `cli/lib/quant/abm_market.cjs`.
+- Simulate-agents handler module: `cli/lib/simulate_handlers/agents.cjs`.
+- Supported handler flags:
+  - `--n-informed` or `--n_informed`
+  - `--n-noise` or `--n_noise`
+  - `--n-mm` or `--n_mm`
+  - `--n-steps` or `--n_steps`
+  - `--seed`
+- ABM payload fields include:
+  - `convergenceError`
+  - `spreadTrajectory[]`
+  - `volume` (`total`, `averagePerStep`, `byAgentType`)
+  - `pnlByAgentType`
+  - `runtimeBounds` (`complexity`, `estimatedAgentDecisions`, `estimatedWorkUnits`)
+- Runtime bound metadata is documented as `O(n_steps * (n_informed + n_noise))`.
+- Unit coverage for this baseline is in `tests/unit/abm_market.test.cjs`.
+
 ## Docs
 
 - Full command contract and workflows: [`SKILL.md`](./SKILL.md)

package/README_FOR_SHARING.md

@@ -136,6 +136,27 @@ Prerequisite: Node.js `>=18`.
   - `pandora resolve`
 - `pandora lp add|remove|positions`
 
+## Quant ABM baseline (current implementation)
+- Deterministic ABM engine module:
+  - `cli/lib/quant/abm_market.cjs`
+- Simulate-agents handler module:
+  - `cli/lib/simulate_handlers/agents.cjs`
+- Handler parser accepts:
+  - `--n-informed|--n_informed`
+  - `--n-noise|--n_noise`
+  - `--n-mm|--n_mm`
+  - `--n-steps|--n_steps`
+  - `--seed`
+- ABM output fields include:
+  - `convergenceError`
+  - `spreadTrajectory[]`
+  - `volume` (`total`, `averagePerStep`, `byAgentType`)
+  - `pnlByAgentType`
+  - `runtimeBounds` with complexity `O(n_steps * (n_informed + n_noise))`
+- Coverage notes:
+  - `tests/unit/abm_market.test.cjs` validates deterministic seed behavior, required ABM metrics, parser/handler behavior, and runtime-bound calculations.
+  - `package.json` `test:unit` includes the ABM suite in default unit execution.
+
 ## Agent-native expansion details
 
 ### MCP server (`pandora mcp`)

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pandora-cli-skills
 summary: Canonical skill and operator guide for Pandora CLI including mirror, polymarket, resolve, and LP flows.
-version: 1.1.43
+version: 1.1.44
 ---
 
 # Pandora CLI & Skills
@@ -48,6 +48,7 @@ npm link
 - Phase 3 analytics command: `pandora portfolio`
 - Phase 3 monitoring command: `pandora watch`
 - Phase 3 watch alerts: `--alert-yes-*`, `--alert-net-liquidity-*`, `--fail-on-alert`
+- Phase 3 forecast scoring flags: `--track-brier`, `--brier-source`, `--brier-file`
 - Phase 4 commands:
   - `pandora history`
   - `pandora export`
@@ -61,6 +62,9 @@ npm link
   - `pandora resolve`
   - `pandora lp add|remove|positions`
   - `pandora stream prices|events`
+- Quant/model commands:
+  - `pandora simulate mc|particle-filter|agents`
+  - `pandora model calibrate|correlation|diagnose|score brier`
 - Fork runtime flags for transaction families:
   - `--fork`
   - `--fork-rpc-url <url>`
@@ -80,6 +84,29 @@ npm link
   - `max_daily_loss_usd` is enforced as daily live notional (`counters.liveNotionalUsdc`).
   - `max_open_markets` is enforced as daily live operation count (`counters.liveOps`).
 
+## Quant ABM baseline (module contract)
+- Deterministic ABM core:
+  - `cli/lib/quant/abm_market.cjs`
+- Simulate-agents handler:
+  - `cli/lib/simulate_handlers/agents.cjs`
+- Handler flags:
+  - `--n-informed|--n_informed`
+  - `--n-noise|--n_noise`
+  - `--n-mm|--n_mm`
+  - `--n-steps|--n_steps`
+  - `--seed`
+- ABM payload fields:
+  - `convergenceError`
+  - `spreadTrajectory[]`
+  - `volume` (`total`, `averagePerStep`, `byAgentType`)
+  - `pnlByAgentType`
+  - `runtimeBounds` (`complexity`, `estimatedAgentDecisions`, `estimatedWorkUnits`)
+- Runtime complexity metadata: `O(n_steps * (n_informed + n_noise))`.
+- Unit coverage:
+  - `tests/unit/abm_market.test.cjs`
+- Note:
+  - This section documents the current module + handler contract. Top-level simulate namespace routing can consume this handler when wired by command service.
+
 ## Complete command + flag reference (authoritative)
 This section mirrors live CLI help output so agent runs can rely on one source of truth.
 
@@ -93,7 +120,7 @@ pandora [--output table|json] markets list [--limit <n>] [--after <cursor>] [--b
 pandora [--output table|json] markets get [--id <id> ...] [--stdin]
 pandora [--output table|json] sports books list|events list|events live|odds snapshot|odds bulk|consensus|create plan|create run|sync once|sync run|sync start|sync stop|sync status|resolve plan [flags]
 pandora [--output table|json] lifecycle start --config <path>|status --id <id>|resolve --id <id> --confirm
-pandora arb scan --markets <csv> --output ndjson|json [--min-net-spread-pct <n>] [--fee-pct-per-leg <n>] [--amount-usdc <n>] [--iterations <n>] [--interval-ms <ms>]
+pandora arb scan --markets <csv> --output ndjson|json [--min-net-spread-pct <n>] [--fee-pct-per-leg <n>] [--slippage-pct-per-leg <n>] [--amount-usdc <n>] [--combinatorial] [--max-bundle-size <n>] [--iterations <n>] [--interval-ms <ms>]
 pandora [--output table|json] odds record --competition <id> --interval <sec> [--max-samples <n>] [--event-id <id>] [--venues pandora_amm,polymarket]
 pandora [--output table|json] odds history --event-id <id> --output csv|json [--limit <n>]
 pandora [--output table|json] polls list [--limit <n>] [--after <cursor>] [--before <cursor>] [--order-by <field>] [--order-direction asc|desc] [--chain-id <id>] [--creator <address>] [--status <int>] [--category <int>] [--question-contains <text>] [--where-json <json>]
@@ -102,7 +129,7 @@ pandora [--output table|json] events list [--type all|liquidity|oracle-fee|claim
 pandora [--output table|json] events get --id <id> [--type all|liquidity|oracle-fee|claim]
 pandora [--output table|json] positions list [--wallet <address>] [--market-address <address>] [--chain-id <id>] [--limit <n>] [--after <cursor>] [--before <cursor>] [--order-by <field>] [--order-direction asc|desc] [--where-json <json>]
 pandora [--output table|json] portfolio --wallet <address> [--chain-id <id>] [--limit <n>] [--include-events|--no-events] [--with-lp] [--rpc-url <url>]
-pandora [--output table|json] watch [--wallet <address>] [--market-address <address>] [--side yes|no] [--amount-usdc <amount>] [--iterations <n>] [--interval-ms <ms>] [--chain-id <id>] [--include-events|--no-events] [--yes-pct <0-100>] [--alert-yes-below <0-100>] [--alert-yes-above <0-100>] [--alert-net-liquidity-below <amount>] [--alert-net-liquidity-above <amount>] [--fail-on-alert]
+pandora [--output table|json] watch [--wallet <address>] [--market-address <address>] [--side yes|no] [--amount-usdc <amount>] [--iterations <n>] [--interval-ms <ms>] [--chain-id <id>] [--include-events|--no-events] [--yes-pct <0-100>] [--alert-yes-below <0-100>] [--alert-yes-above <0-100>] [--alert-net-liquidity-below <amount>] [--alert-net-liquidity-above <amount>] [--fail-on-alert] [--track-brier] [--brier-source <name>] [--brier-file <path>] [--group-by source|market|competition]
 pandora [--output table|json] scan [--limit <n>] [--after <cursor>] [--before <cursor>] [--order-by <field>] [--order-direction asc|desc] [--chain-id <id>] [--creator <address>] [--poll-address <address>] [--market-type <type>] [--where-json <json>] [--active|--resolved|--expiring-soon] [--expiring-hours <n>] [--expand]
 pandora [--output table|json] quote [--indexer-url <url>] [--timeout-ms <ms>] --market-address <address> --side yes|no --amount-usdc <amount> [--yes-pct <0-100>] [--slippage-bps <0-10000>]
 pandora [--output table|json] trade [--indexer-url <url>] [--timeout-ms <ms>] [--dotenv-path <path>] [--skip-dotenv] --market-address <address> --side yes|no --amount-usdc <amount> --dry-run|--execute [--yes-pct <0-100>] [--slippage-bps <0-10000>] [--min-shares-out-raw <uint>] [--max-amount-usdc <amount>] [--min-probability-pct <0-100>] [--max-probability-pct <0-100>] [--allow-unquoted-execute] [--fork] [--fork-rpc-url <url>] [--fork-chain-id <id>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--usdc <address>]
@@ -111,6 +138,8 @@ pandora [--output table|json] export --wallet <address> --format csv|json [--cha
 pandora [--output table|json] arbitrage [--chain-id <id>] [--venues pandora,polymarket] [--limit <n>] [--min-spread-pct <n>] [--min-liquidity-usdc <n>] [--max-close-diff-hours <n>] [--similarity-threshold <0-1>] [--cross-venue-only|--allow-same-venue] [--with-rules] [--include-similarity] [--question-contains <text>] [--polymarket-host <url>] [--polymarket-mock-url <url>]
 pandora [--output table|json] autopilot run|once --market-address <address> --side yes|no --amount-usdc <amount> [--trigger-yes-below <0-100>] [--trigger-yes-above <0-100>] [--paper|--execute-live] [--interval-ms <ms>] [--cooldown-ms <ms>] [--max-amount-usdc <amount>] [--max-open-exposure-usdc <amount>] [--max-trades-per-day <n>] [--state-file <path>] [--kill-switch-file <path>] [--webhook-url <url>] [--telegram-bot-token <token>] [--telegram-chat-id <id>] [--discord-webhook-url <url>]
 pandora [--output table|json] mirror browse|plan|deploy|verify|lp-explain|hedge-calc|simulate|go|sync|status|close ...
+pandora [--output table|json] simulate mc|particle-filter|agents ...
+pandora [--output table|json] model calibrate|correlation|diagnose|score brier ...
 pandora [--output table|json] polymarket check|approve|preflight|trade ...
 pandora [--output table|json] webhook test [--webhook-url <url>] [--webhook-template <json>] [--webhook-secret <secret>] [--telegram-bot-token <token>] [--telegram-chat-id <id>] [--discord-webhook-url <url>] [--webhook-timeout-ms <ms>] [--webhook-retries <n>]
 pandora [--output table|json] leaderboard [--metric profit|volume|win-rate] [--chain-id <id>] [--limit <n>] [--min-trades <n>]
@@ -131,12 +160,12 @@ Mirror subcommand detail:
 ```text
 browse --min-yes-pct <n> --max-yes-pct <n> --min-volume-24h <n> [--closes-after <date>] [--closes-before <date>] [--question-contains <text>] [--limit <n>] [--chain-id <id>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]
 plan   --source polymarket --polymarket-market-id <id>|--polymarket-slug <slug> [--chain-id <id>] [--target-slippage-bps <n>] [--turnover-target <n>] [--depth-slippage-bps <n>] [--safety-multiplier <n>] [--min-liquidity-usdc <n>] [--max-liquidity-usdc <n>] [--with-rules] [--include-similarity] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]
-deploy --plan-file <path>|--polymarket-market-id <id>|--polymarket-slug <slug> --dry-run|--execute [--liquidity-usdc <n>] [--fee-tier 500|3000|10000] [--max-imbalance <n>] [--arbiter <address>] [--category <n>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--oracle <address>] [--factory <address>] [--usdc <address>] [--distribution-yes <parts>] [--distribution-no <parts>] [--sources <url...>] [--min-close-lead-seconds <n>] [--manifest-file <path>] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]
+deploy --plan-file <path>|--polymarket-market-id <id>|--polymarket-slug <slug> --dry-run|--execute [--liquidity-usdc <n>] [--fee-tier <500-50000>] [--max-imbalance <n>] [--arbiter <address>] [--category <n>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--oracle <address>] [--factory <address>] [--usdc <address>] [--distribution-yes <parts>] [--distribution-no <parts>] [--sources <url...>] [--min-close-lead-seconds <n>] [--manifest-file <path>] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]
 verify --pandora-market-address <address>|--market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug> [--trust-deploy] [--manifest-file <path>] [--include-similarity] [--with-rules] [--allow-rule-mismatch] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]
 lp-explain --liquidity-usdc <n> [--source-yes-pct <0-100>] [--distribution-yes <parts>] [--distribution-no <parts>]
 hedge-calc [--reserve-yes-usdc <n> --reserve-no-usdc <n>] [--excess-yes-usdc <n>] [--excess-no-usdc <n>] [--polymarket-yes-pct <0-100>] [--hedge-ratio <n>] [--hedge-cost-bps <n>] [--volume-scenarios <csv>] [--pandora-market-address <address>|--market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug>] [--trust-deploy] [--manifest-file <path>]
-simulate --liquidity-usdc <n> [--source-yes-pct <0-100>] [--target-yes-pct <0-100>] [--distribution-yes <parts>] [--distribution-no <parts>] [--fee-tier 500|3000|10000] [--volume-scenarios <csv>] [--hedge-ratio <n>] [--hedge-cost-bps <n>] [--polymarket-yes-pct <0-100>]
-go     --polymarket-market-id <id>|--polymarket-slug <slug> [--liquidity-usdc <n>] [--fee-tier 500|3000|10000] [--max-imbalance <n>] [--arbiter <address>] [--category <n>] [--paper|--dry-run|--execute-live|--execute] [--auto-sync] [--sync-once] [--sync-interval-ms <ms>] [--hedge-ratio <n>] [--no-hedge] [--max-rebalance-usdc <n>] [--max-hedge-usdc <n>] [--max-open-exposure-usdc <n>] [--max-trades-per-day <n>] [--cooldown-ms <ms>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--funder <address>] [--usdc <address>] [--oracle <address>] [--factory <address>] [--sources <url...>] [--manifest-file <path>] [--trust-deploy] [--skip-gate] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>] [--with-rules] [--include-similarity] [--min-close-lead-seconds <n>]
+simulate --liquidity-usdc <n> [--source-yes-pct <0-100>] [--target-yes-pct <0-100>] [--distribution-yes <parts>] [--distribution-no <parts>] [--fee-tier <500-50000>] [--volume-scenarios <csv>] [--hedge-ratio <n>] [--hedge-cost-bps <n>] [--polymarket-yes-pct <0-100>]
+go     --polymarket-market-id <id>|--polymarket-slug <slug> [--liquidity-usdc <n>] [--fee-tier <500-50000>] [--max-imbalance <n>] [--arbiter <address>] [--category <n>] [--paper|--dry-run|--execute-live|--execute] [--auto-sync] [--sync-once] [--sync-interval-ms <ms>] [--hedge-ratio <n>] [--no-hedge] [--max-rebalance-usdc <n>] [--max-hedge-usdc <n>] [--max-open-exposure-usdc <n>] [--max-trades-per-day <n>] [--cooldown-ms <ms>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--funder <address>] [--usdc <address>] [--oracle <address>] [--factory <address>] [--sources <url...>] [--manifest-file <path>] [--trust-deploy] [--skip-gate] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>] [--with-rules] [--include-similarity] [--min-close-lead-seconds <n>]
 sync run|once|start --pandora-market-address <address>|--market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug> [--paper|--dry-run|--execute-live|--execute] [--private-key <hex>] [--funder <address>] [--usdc <address>] [--trust-deploy] [--manifest-file <path>] [--skip-gate] [--daemon] [--stream|--no-stream] [--interval-ms <ms>] [--drift-trigger-bps <n>] [--hedge-trigger-usdc <n>] [--hedge-ratio <n>] [--no-hedge] [--max-rebalance-usdc <n>] [--max-hedge-usdc <n>] [--max-open-exposure-usdc <n>] [--max-trades-per-day <n>] [--cooldown-ms <ms>] [--depth-slippage-bps <n>] [--min-time-to-close-sec <n>] [--iterations <n>] [--state-file <path>] [--kill-switch-file <path>] [--chain-id <id>] [--rpc-url <url>] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>] [--webhook-url <url>] [--telegram-bot-token <token>] [--telegram-chat-id <id>] [--discord-webhook-url <url>]
 status --state-file <path>|--strategy-hash <hash> [--with-live] [--pandora-market-address <address>|--market-address <address>] [--polymarket-market-id <id>|--polymarket-slug <slug>]
 close  --pandora-market-address <address>|--market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug> --dry-run|--execute
@@ -158,6 +187,18 @@ preflight [--fork] [--fork-rpc-url <url>] [--fork-chain-id <id>] [--rpc-url <url
 trade --condition-id <id>|--slug <slug>|--token-id <id> --token yes|no --amount-usdc <n> --dry-run|--execute [--side buy|sell] [--polymarket-host <url>] [--polymarket-mock-url <url>] [--timeout-ms <ms>] [--fork] [--fork-rpc-url <url>] [--fork-chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--funder <address>]
 ```
 
+Simulate/model subcommand detail:
+
+```text
+simulate mc [--trials <n>] [--horizon <n>] [--start-yes-pct <0-100>] [--entry-yes-pct <0-100>] [--position yes|no] [--stake-usdc <n>] [--drift-bps <n>] [--vol-bps <n>] [--confidence <50-100>] [--var-level <50-100>] [--seed <n>] [--antithetic] [--stratified]
+simulate particle-filter (--observations-json <json>|--input <path>|--stdin) [--particles <n>] [--process-noise <n>] [--observation-noise <n>] [--drift-bps <n>] [--initial-yes-pct <0-100>] [--initial-spread <n>] [--resample-threshold <0-1>] [--resample-method systematic|multinomial] [--credible-interval <50-100>] [--seed <n>]
+simulate agents [--n-informed <n>] [--n-noise <n>] [--n-mm <n>] [--n-steps <n>] [--seed <int>]
+model calibrate (--prices <csv>|--returns <csv>) [--dt <n>] [--jump-threshold-sigma <n>] [--min-jump-count <n>] [--model-id <id>] [--save-model <path>]
+model correlation --series <id:v1,v2,...> --series <id:v1,v2,...> [--copula t|gaussian|clayton|gumbel] [--compare <csv>] [--tail-alpha <n>] [--df <n>] [--joint-threshold-z <n>] [--scenario-shocks <csv>] [--model-id <id>] [--save-model <path>]
+model diagnose [--calibration-rmse <n>] [--drift-bps <n>] [--spread-bps <n>] [--depth-coverage <0..1>] [--informed-flow-ratio <0..1>] [--noise-ratio <0..1>] [--anomaly-rate <0..1>] [--manipulation-alerts <n>] [--tail-dependence <0..1>]
+model score brier [--source <name>] [--market-address <address>] [--competition <id>] [--event-id <id>] [--model-id <id>] [--group-by source|market|competition|model|none] [--window-days <n>] [--bucket-count <n>] [--forecast-file <path>] [--include-records] [--include-unresolved] [--limit <n>]
+```
+
 ## Sports command matrix
 | Command | Purpose | Primary flags |
 | --- | --- | --- |
@@ -448,6 +489,10 @@ Common structured error codes for automation:
 - `ODDS_*`: odds record/history storage and connector failures.
 - `ARB_*`: arb scan parsing/execution output-mode failures.
 - `CONFIG_*`: config read/parse failures (for example `CONFIG_FILE_NOT_FOUND`).
+- `SIMULATE_*`: simulate namespace failures (`SIMULATE_MC_INVALID_INPUT`, `SIMULATE_PARTICLE_FILTER_FAILED`, `SIMULATE_AGENTS_FAILED`).
+- `MODEL_*`: model namespace failures (`MODEL_CALIBRATE_INVALID_INPUT`, `MODEL_CORRELATION_FAILED`, `MODEL_DIAGNOSE_INVALID_INPUT`, `MODEL_SCORE_BRIER_FAILED`).
+- `FORECAST_*`: forecast ledger read/write/normalization failures (`FORECAST_WRITE_FAILED`, `FORECAST_INVALID_RECORD`, `FORECAST_READ_FAILED`).
+- `BRIER_*`: brier scoring input/grouping failures (`BRIER_INVALID_INPUT`, `BRIER_INVALID_GROUP_BY`, `BRIER_FAILED`).
 - `MCP_FILE_ACCESS_BLOCKED`: MCP-mode file path denied outside workspace root.
 - `WEBHOOK_DELIVERY_FAILED`: webhook hard-fail when `--fail-on-webhook-error` is set.
 
@@ -530,6 +575,15 @@ Error envelope:
   - `lp positions`: `{ ok: true, command: "lp", data: { schemaVersion, generatedAt, action: "positions", mode: "read", wallet, count, items[] } }`
 - `polymarket`:
   - `check|preflight|approve|trade` all return `{ ok: true, command, data }` with `schemaVersion` and `generatedAt`; execute paths include `result`/`tx` blocks.
+- `simulate`:
+  - `simulate.mc`: `{ ok: true, command: "simulate.mc", data: { schemaVersion, generatedAt, inputs, summary, distribution, diagnostics[] } }`
+  - `simulate.particle-filter`: `{ ok: true, command: "simulate.particle-filter", data: { schemaVersion, generatedAt, inputs, summary, trajectory[], diagnostics[] } }`
+  - `simulate.agents`: `{ ok: true, command: "simulate.agents", data: { schemaVersion, generatedAt, parameters, convergenceError, spreadTrajectory[], volume, pnlByAgentType, finalState, runtimeBounds } }`
+- `model`:
+  - `model.calibrate`: `{ ok: true, command: "model.calibrate", data: { schemaVersion, generatedAt, action: "calibrate", model, diagnostics, persistence } }`
+  - `model.correlation`: `{ ok: true, command: "model.correlation", data: { schemaVersion, generatedAt, action: "correlation", copula, metrics, stress, comparisons, diagnostics, model, persistence } }`
+  - `model.diagnose`: `{ ok: true, command: "model.diagnose", data: { schemaVersion, generatedAt, inputs, components, aggregate, recommendations, flags, diagnostics[] } }`
+  - `model.score.brier`: `{ ok: true, command: "model.score.brier", data: { schemaVersion, generatedAt, action: "score.brier", filters, ledger, report, diagnostics[] } }`
 - `leaderboard`:
   - `{ ok: true, command: "leaderboard", data: { schemaVersion, generatedAt, indexerUrl, metric, limit, minTrades, count, items[], diagnostics[] } }`
 - `analyze`:

package/cli/lib/arb_command_service.cjs

@@ -14,7 +14,7 @@ const ARB_MARKET_FIELDS = [
 ];
 
 const ARB_USAGE =
-  'pandora arb scan --markets <csv> --output ndjson|json [--min-net-spread-pct <n>] [--fee-pct-per-leg <n>] [--amount-usdc <n>] [--interval-ms <ms>] [--iterations <n>] [--indexer-url <url>] [--timeout-ms <ms>]';
+  'pandora arb scan --markets <csv> --output ndjson|json [--min-net-spread-pct <n>] [--fee-pct-per-leg <n>] [--slippage-pct-per-leg <n>] [--amount-usdc <n>] [--combinatorial] [--max-bundle-size <n>] [--interval-ms <ms>] [--iterations <n>] [--indexer-url <url>] [--timeout-ms <ms>]';
 
 function requireDep(deps, name) {
   if (!deps || typeof deps[name] !== 'function') {
@@ -139,6 +139,114 @@ function buildArbOpportunities(options) {
   return opportunities;
 }
 
+function enumerateCombinations(items, size, onCombination) {
+  if (!Array.isArray(items) || !Number.isInteger(size) || size < 1 || size > items.length) return;
+  if (typeof onCombination !== 'function') return;
+
+  const selected = [];
+  function walk(startIndex) {
+    if (selected.length === size) {
+      onCombination(selected.slice());
+      return;
+    }
+    const remaining = size - selected.length;
+    const maxStart = items.length - remaining;
+    for (let index = startIndex; index <= maxStart; index += 1) {
+      selected.push(items[index]);
+      walk(index + 1);
+      selected.pop();
+    }
+  }
+  walk(0);
+}
+
+/**
+ * Build bundle-level combinatorial opportunities across provided markets.
+ * @param {object} options
+ * @returns {object[]}
+ */
+function buildCombinatorialArbOpportunities(options) {
+  const marketSnapshots = Array.isArray(options.marketSnapshots)
+    ? options.marketSnapshots.filter((item) => item && Number.isFinite(item.yesPct))
+    : [];
+  if (marketSnapshots.length < 3) return [];
+
+  const minNetSpreadPct = Number.isFinite(options.minNetSpreadPct) ? Number(options.minNetSpreadPct) : 0;
+  const feePctPerLeg = Number.isFinite(options.feePctPerLeg) ? Number(options.feePctPerLeg) : 0;
+  const slippagePctPerLeg = Number.isFinite(options.slippagePctPerLeg) ? Number(options.slippagePctPerLeg) : 0;
+  const amountUsdc = Number.isFinite(options.amountUsdc) ? Number(options.amountUsdc) : 0;
+  const requestedMaxBundleSize = Number.isInteger(options.maxBundleSize) ? options.maxBundleSize : 4;
+  const maxBundleSize = Math.max(3, Math.min(requestedMaxBundleSize, marketSnapshots.length));
+
+  const opportunities = [];
+  for (let bundleSize = 3; bundleSize <= maxBundleSize; bundleSize += 1) {
+    enumerateCombinations(marketSnapshots, bundleSize, (bundle) => {
+      const bundleMarketIds = bundle.map((item) => item.id);
+      const sumYesPct = roundNumber(bundle.reduce((total, item) => total + Number(item.yesPct), 0), 6);
+      const sumNoPct = roundNumber(bundle.reduce((total, item) => total + (100 - Number(item.yesPct)), 0), 6);
+      const feeImpactPct = roundNumber(bundleSize * feePctPerLeg, 6);
+      const slippageImpactPct = roundNumber(bundleSize * slippagePctPerLeg, 6);
+
+      const evaluate = (strategy) => {
+        const grossEdgePct = strategy === 'buy_yes_bundle' ? roundNumber(100 - sumYesPct, 6) : roundNumber(sumYesPct - 100, 6);
+        if (grossEdgePct <= 0) return;
+
+        const netSpreadPct = roundNumber(grossEdgePct - feeImpactPct - slippageImpactPct, 6);
+        if (netSpreadPct <= 0 || netSpreadPct < minNetSpreadPct) return;
+
+        const payoutPct = strategy === 'buy_yes_bundle' ? 100 : roundNumber((bundleSize - 1) * 100, 6);
+        const totalEntryPct = strategy === 'buy_yes_bundle' ? sumYesPct : sumNoPct;
+        const grossProfitUsdc = roundNumber((amountUsdc * grossEdgePct) / 100, 6);
+        const profitUsdc = roundNumber((amountUsdc * netSpreadPct) / 100, 6);
+
+        opportunities.push({
+          opportunityType: 'combinatorial',
+          strategy,
+          pair: `bundle:${bundleMarketIds.join('|')}:${strategy}`,
+          bundleMarketIds,
+          bundleSize,
+          legs: bundle.map((item) => ({
+            marketId: item.id,
+            yesPct: roundNumber(item.yesPct, 6),
+            noPct: roundNumber(100 - item.yesPct, 6),
+          })),
+          sumYesPct,
+          sumNoPct,
+          totalEntryPct,
+          payoutPct,
+          grossSpreadPct: grossEdgePct,
+          grossEdgePct,
+          feePctPerLeg: roundNumber(feePctPerLeg, 6),
+          slippagePctPerLeg: roundNumber(slippagePctPerLeg, 6),
+          feeImpactPct,
+          slippageImpactPct,
+          netSpreadPct,
+          netSpread: roundNumber(netSpreadPct / 100, 8),
+          amountUsdc: roundNumber(amountUsdc, 6),
+          grossProfitUsdc,
+          profitUsdc,
+          profit: profitUsdc,
+        });
+      };
+
+      evaluate('buy_yes_bundle');
+      evaluate('buy_no_bundle');
+    });
+  }
+
+  opportunities.sort((left, right) => {
+    if (right.netSpreadPct !== left.netSpreadPct) {
+      return right.netSpreadPct - left.netSpreadPct;
+    }
+    if (right.bundleSize !== left.bundleSize) {
+      return right.bundleSize - left.bundleSize;
+    }
+    return left.pair.localeCompare(right.pair);
+  });
+
+  return opportunities;
+}
+
 /**
  * Parse `arb scan` command flags.
  * @param {string[]} args
@@ -159,7 +267,10 @@ function parseArbScanFlags(args, deps) {
     output: 'ndjson',
     minNetSpreadPct: 0,
     feePctPerLeg: 0,
+    slippagePctPerLeg: 0,
     amountUsdc: 100,
+    combinatorial: false,
+    maxBundleSize: 4,
     intervalMs: 5_000,
     iterations: null,
   };
@@ -187,11 +298,25 @@ function parseArbScanFlags(args, deps) {
       i += 1;
       continue;
     }
+    if (token === '--slippage-pct-per-leg') {
+      options.slippagePctPerLeg = parseNumber(requireFlagValue(rest, i, '--slippage-pct-per-leg'), '--slippage-pct-per-leg');
+      i += 1;
+      continue;
+    }
     if (token === '--amount-usdc') {
       options.amountUsdc = parsePositiveNumber(requireFlagValue(rest, i, '--amount-usdc'), '--amount-usdc');
       i += 1;
       continue;
     }
+    if (token === '--combinatorial') {
+      options.combinatorial = true;
+      continue;
+    }
+    if (token === '--max-bundle-size') {
+      options.maxBundleSize = parsePositiveInteger(requireFlagValue(rest, i, '--max-bundle-size'), '--max-bundle-size');
+      i += 1;
+      continue;
+    }
     if (token === '--interval-ms') {
       options.intervalMs = parsePositiveInteger(requireFlagValue(rest, i, '--interval-ms'), '--interval-ms');
       i += 1;
@@ -222,6 +347,14 @@ function parseArbScanFlags(args, deps) {
     throw new CliError('INVALID_FLAG_VALUE', '--fee-pct-per-leg must be >= 0.');
   }
 
+  if (options.slippagePctPerLeg < 0) {
+    throw new CliError('INVALID_FLAG_VALUE', '--slippage-pct-per-leg must be >= 0.');
+  }
+
+  if (!Number.isInteger(options.maxBundleSize) || options.maxBundleSize < 3) {
+    throw new CliError('INVALID_FLAG_VALUE', '--max-bundle-size must be an integer >= 3.');
+  }
+
   options.markets = Array.from(
     new Set(
       options.markets
@@ -234,6 +367,10 @@ function parseArbScanFlags(args, deps) {
     throw new CliError('INVALID_ARGS', 'arb scan requires at least two distinct market ids.');
   }
 
+  if (options.combinatorial && options.markets.length < 3) {
+    throw new CliError('INVALID_ARGS', 'arb scan --combinatorial requires at least three distinct market ids.');
+  }
+
   return options;
 }
 
@@ -313,7 +450,8 @@ function createRunArbCommand(deps) {
 
     const maxIterations = Number.isInteger(options.iterations) ? options.iterations : Number.POSITIVE_INFINITY;
     let iteration = 0;
-    const snapshots = [];
+    const iterationSnapshots = [];
+    let emittedCombinatorialCount = 0;
 
     while (iteration < maxIterations) {
       iteration += 1;
@@ -321,13 +459,30 @@ function createRunArbCommand(deps) {
         buildGraphqlGetQuery,
         graphqlRequest,
       });
-      const snapshots = buildMarketSnapshots(markets, options.markets);
-      const opportunities = buildArbOpportunities({
-        marketSnapshots: snapshots,
+      const marketSnapshots = buildMarketSnapshots(markets, options.markets);
+      const pairwiseOpportunities = buildArbOpportunities({
+        marketSnapshots,
         minNetSpreadPct: options.minNetSpreadPct,
         feePctPerLeg: options.feePctPerLeg,
         amountUsdc: options.amountUsdc,
       });
+      const combinatorialOpportunities = options.combinatorial
+        ? buildCombinatorialArbOpportunities({
+            marketSnapshots,
+            minNetSpreadPct: options.minNetSpreadPct,
+            feePctPerLeg: options.feePctPerLeg,
+            slippagePctPerLeg: options.slippagePctPerLeg,
+            amountUsdc: options.amountUsdc,
+            maxBundleSize: options.maxBundleSize,
+          })
+        : [];
+      emittedCombinatorialCount += combinatorialOpportunities.length;
+      const opportunities = [...pairwiseOpportunities, ...combinatorialOpportunities].sort((left, right) => {
+        if (right.netSpreadPct !== left.netSpreadPct) {
+          return right.netSpreadPct - left.netSpreadPct;
+        }
+        return String(left.pair || '').localeCompare(String(right.pair || ''));
+      });
 
       if (options.output === 'ndjson') {
         for (const opportunity of opportunities) {
@@ -343,10 +498,12 @@ function createRunArbCommand(deps) {
           );
         }
       } else {
-        snapshots.push({
+        iterationSnapshots.push({
           iteration,
           observedAt: new Date().toISOString(),
           count: opportunities.length,
+          pairwiseCount: pairwiseOpportunities.length,
+          combinatorialCount: combinatorialOpportunities.length,
           opportunities,
         });
       }
@@ -357,6 +514,11 @@ function createRunArbCommand(deps) {
     }
 
     if (options.output === 'json') {
+      const diagnostics = [];
+      if (options.combinatorial && emittedCombinatorialCount === 0) {
+        diagnostics.push('No combinatorial bundles cleared net spread thresholds for this run.');
+      }
+
       const payload = {
         action: 'scan',
         indexerUrl,
@@ -367,11 +529,14 @@ function createRunArbCommand(deps) {
           markets: options.markets,
           minNetSpreadPct: options.minNetSpreadPct,
           feePctPerLeg: options.feePctPerLeg,
+          slippagePctPerLeg: options.slippagePctPerLeg,
           amountUsdc: options.amountUsdc,
+          combinatorial: options.combinatorial,
+          maxBundleSize: options.maxBundleSize,
         },
-        opportunities: snapshots.flatMap((row) => row.opportunities),
-        snapshots,
-        diagnostics: [],
+        opportunities: iterationSnapshots.flatMap((row) => row.opportunities),
+        snapshots: iterationSnapshots,
+        diagnostics,
       };
 
       if (context.outputMode === 'json') {
@@ -387,6 +552,7 @@ function createRunArbCommand(deps) {
 module.exports = {
   ARB_USAGE,
   buildArbOpportunities,
+  buildCombinatorialArbOpportunities,
   createRunArbCommand,
   parseArbScanFlags,
 };