pandora-cli-skills 1.1.43 → 1.1.44

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
@@ -80,6 +80,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.
 
@@ -131,12 +154,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

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,
 };

package/cli/lib/arbitrage_service.cjs

@@ -410,8 +410,147 @@ function summarizeGroup(group, options, acceptedPairChecks) {
   };
 }
 
+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);
+}
+
+function resolveCombinatorialSettings(options) {
+  return {
+    enabled: Boolean(options && options.combinatorial),
+    minNetEdgePct: Number.isFinite(options && options.minSpreadPct) ? Number(options.minSpreadPct) : 0,
+    feePctPerLeg: Number.isFinite(options && options.combinatorialFeePctPerLeg)
+      ? Number(options.combinatorialFeePctPerLeg)
+      : Number.isFinite(options && options.feePctPerLeg)
+        ? Number(options.feePctPerLeg)
+        : 0,
+    slippagePctPerLeg: Number.isFinite(options && options.combinatorialSlippagePctPerLeg)
+      ? Number(options.combinatorialSlippagePctPerLeg)
+      : Number.isFinite(options && options.slippagePctPerLeg)
+        ? Number(options.slippagePctPerLeg)
+        : 0,
+    amountUsdc: Number.isFinite(options && options.combinatorialAmountUsdc)
+      ? Number(options.combinatorialAmountUsdc)
+      : Number.isFinite(options && options.amountUsdc)
+        ? Number(options.amountUsdc)
+        : 100,
+    maxBundleSize: Number.isInteger(options && options.maxBundleSize) ? Number(options.maxBundleSize) : 4,
+  };
+}
+
+function buildCombinatorialBundleOpportunities(group, summary, options) {
+  const settings = resolveCombinatorialSettings(options);
+  if (!settings.enabled) return [];
+
+  const legs = Array.isArray(group)
+    ? group.filter(
+        (leg) => leg && Number.isFinite(toNumber(leg.yesPct)) && Number.isFinite(toNumber(leg.noPct)),
+      )
+    : [];
+  if (legs.length < 3) return [];
+
+  const maxBundleSize = Math.max(3, Math.min(settings.maxBundleSize, legs.length));
+  const opportunities = [];
+
+  for (let bundleSize = 3; bundleSize <= maxBundleSize; bundleSize += 1) {
+    enumerateCombinations(legs, bundleSize, (bundle) => {
+      const bundleMarketIds = bundle.map((leg) => leg.marketId);
+      const bundleVenues = Array.from(new Set(bundle.map((leg) => leg.venue))).sort();
+      const bundleCloseValues = bundle.map((leg) => toNumber(leg.closeTimestamp)).filter((value) => value !== null);
+      const sumYesPct = round(bundle.reduce((total, leg) => total + Number(leg.yesPct), 0), 6);
+      const sumNoPct = round(bundle.reduce((total, leg) => total + Number(leg.noPct), 0), 6);
+      const feeImpactPct = round(bundleSize * settings.feePctPerLeg, 6);
+      const slippageImpactPct = round(bundleSize * settings.slippagePctPerLeg, 6);
+
+      const evaluate = (strategy) => {
+        const grossEdgePct = strategy === 'buy_yes_bundle' ? round(100 - sumYesPct, 6) : round(sumYesPct - 100, 6);
+        if (grossEdgePct <= 0) return;
+
+        const netEdgePct = round(grossEdgePct - feeImpactPct - slippageImpactPct, 6);
+        if (netEdgePct <= 0 || netEdgePct < settings.minNetEdgePct) return;
+
+        const payoutPct = strategy === 'buy_yes_bundle' ? 100 : round((bundleSize - 1) * 100, 6);
+        const totalEntryPct = strategy === 'buy_yes_bundle' ? sumYesPct : sumNoPct;
+        const grossProfitUsdc = round((settings.amountUsdc * grossEdgePct) / 100, 6);
+        const profitUsdc = round((settings.amountUsdc * netEdgePct) / 100, 6);
+
+        opportunities.push({
+          opportunityType: 'combinatorial',
+          strategy,
+          groupId: summary.groupId,
+          normalizedQuestion: summary.normalizedQuestion,
+          bundleSize,
+          bundleMarketIds,
+          bundleVenues,
+          closeTimeWindow: {
+            min: bundleCloseValues.length ? Math.min(...bundleCloseValues) : null,
+            max: bundleCloseValues.length ? Math.max(...bundleCloseValues) : null,
+          },
+          sumYesPct,
+          sumNoPct,
+          totalEntryPct,
+          payoutPct,
+          grossEdgePct,
+          feePctPerLeg: round(settings.feePctPerLeg, 6),
+          slippagePctPerLeg: round(settings.slippagePctPerLeg, 6),
+          feeImpactPct,
+          slippageImpactPct,
+          netEdgePct,
+          netEdge: round(netEdgePct / 100, 8),
+          amountUsdc: round(settings.amountUsdc, 6),
+          grossProfitUsdc,
+          profitUsdc,
+          legs: bundle.map((leg) => ({
+            venue: leg.venue,
+            marketId: leg.marketId,
+            yesPct: leg.yesPct,
+            noPct: leg.noPct,
+            liquidityUsd: leg.liquidityUsd,
+            volumeUsd: leg.volumeUsd,
+            closeTimestamp: leg.closeTimestamp,
+            rules: options.withRules ? leg.rules || null : undefined,
+            sources: options.withRules ? (Array.isArray(leg.sources) ? leg.sources : []) : undefined,
+          })),
+        });
+      };
+
+      evaluate('buy_yes_bundle');
+      evaluate('buy_no_bundle');
+    });
+  }
+
+  opportunities.sort((left, right) => {
+    if (right.netEdgePct !== left.netEdgePct) {
+      return right.netEdgePct - left.netEdgePct;
+    }
+    if (right.bundleSize !== left.bundleSize) {
+      return right.bundleSize - left.bundleSize;
+    }
+    return String(left.groupId || '').localeCompare(String(right.groupId || ''));
+  });
+
+  return opportunities;
+}
+
 async function scanArbitrage(options) {
   const venues = Array.from(new Set((options.venues || ['pandora', 'polymarket']).map((value) => String(value).toLowerCase())));
+  const combinatorialSettings = resolveCombinatorialSettings(options);
 
   const sources = {};
   const allLegs = [];
@@ -492,18 +631,35 @@ async function scanArbitrage(options) {
         withRules: options.withRules,
         includeSimilarity: options.includeSimilarity,
         questionContains: options.questionContains,
+        combinatorial: combinatorialSettings.enabled,
+        maxBundleSize: combinatorialSettings.maxBundleSize,
+        combinatorialFeePctPerLeg: combinatorialSettings.feePctPerLeg,
+        combinatorialSlippagePctPerLeg: combinatorialSettings.slippagePctPerLeg,
+        combinatorialAmountUsdc: combinatorialSettings.amountUsdc,
       },
       sources,
       diagnostics,
       count: 0,
       opportunities: [],
+      ...(combinatorialSettings.enabled
+        ? {
+            bundleCount: 0,
+            bundleOpportunities: [],
+          }
+        : {}),
     };
   }
 
   const grouped = buildGroups(allLegs, options);
-  const opportunities = grouped.groups
-    .map((group) => summarizeGroup(group, options, grouped.acceptedPairChecks))
-    .filter(Boolean)
+  const groupSummaries = grouped.groups
+    .map((group) => ({
+      group,
+      summary: summarizeGroup(group, options, grouped.acceptedPairChecks),
+    }))
+    .filter((entry) => Boolean(entry.summary));
+
+  const opportunities = groupSummaries
+    .map((entry) => entry.summary)
     .sort((a, b) => {
       const left = Math.max(a.spreadYesPct || 0, a.spreadNoPct || 0);
       const right = Math.max(b.spreadYesPct || 0, b.spreadNoPct || 0);
@@ -511,6 +667,22 @@ async function scanArbitrage(options) {
     })
     .slice(0, options.limit);
 
+  const bundleOpportunities = combinatorialSettings.enabled
+    ? groupSummaries
+        .flatMap((entry) => buildCombinatorialBundleOpportunities(entry.group, entry.summary, options))
+        .sort((a, b) => {
+          if ((b.netEdgePct || 0) !== (a.netEdgePct || 0)) {
+            return (b.netEdgePct || 0) - (a.netEdgePct || 0);
+          }
+          return String(a.groupId || '').localeCompare(String(b.groupId || ''));
+        })
+        .slice(0, options.limit)
+    : [];
+
+  if (combinatorialSettings.enabled && bundleOpportunities.length === 0) {
+    diagnostics.push('Combinatorial mode enabled but no bundle opportunities cleared net edge thresholds.');
+  }
+
   return {
     schemaVersion: ARBITRAGE_SCHEMA_VERSION,
     generatedAt: new Date().toISOString(),
@@ -526,16 +698,28 @@ async function scanArbitrage(options) {
       withRules: options.withRules,
       includeSimilarity: options.includeSimilarity,
       questionContains: options.questionContains,
+      combinatorial: combinatorialSettings.enabled,
+      maxBundleSize: combinatorialSettings.maxBundleSize,
+      combinatorialFeePctPerLeg: combinatorialSettings.feePctPerLeg,
+      combinatorialSlippagePctPerLeg: combinatorialSettings.slippagePctPerLeg,
+      combinatorialAmountUsdc: combinatorialSettings.amountUsdc,
     },
     sources,
     diagnostics,
     count: opportunities.length,
     opportunities,
+    ...(combinatorialSettings.enabled
+      ? {
+          bundleCount: bundleOpportunities.length,
+          bundleOpportunities,
+        }
+      : {}),
   };
 }
 
 module.exports = {
   ARBITRAGE_SCHEMA_VERSION,
+  buildCombinatorialBundleOpportunities,
   normalizeQuestion,
   questionSimilarity,
   scanArbitrage,