Phase 0 completion: NT8 SDK core framework with risk management and position sizing

Specs/SDK/core_interfaces_package.md

@@ -0,0 +1,371 @@
+# **Core Interfaces Package**
+
+## **IMPLEMENTATION CHECKLIST**
+
+Create these files exactly as specified:
+
+### **File 1: `src/NT8.Core/Common/Interfaces/IStrategy.cs`**
+```csharp
+using NT8.Core.Common.Models;
+
+namespace NT8.Core.Common.Interfaces;
+
+/// <summary>
+/// Core strategy interface - strategies implement signal generation only
+/// The SDK handles all risk management, position sizing, and order execution
+/// </summary>
+public interface IStrategy
+{
+    /// <summary>
+    /// Strategy metadata and configuration
+    /// </summary>
+    StrategyMetadata Metadata { get; }
+    
+    /// <summary>
+    /// Initialize strategy with configuration and dependencies
+    /// </summary>
+    void Initialize(StrategyConfig config, IMarketDataProvider dataProvider, ILogger logger);
+    
+    /// <summary>
+    /// Process new bar data and generate trading intent (if any)
+    /// This is the main entry point for strategy logic
+    /// </summary>
+    StrategyIntent? OnBar(BarData bar, StrategyContext context);
+    
+    /// <summary>
+    /// Process tick data for high-frequency strategies (optional)
+    /// Most strategies can leave this as default implementation
+    /// </summary>
+    StrategyIntent? OnTick(TickData tick, StrategyContext context) => null;
+    
+    /// <summary>
+    /// Get current strategy parameters for serialization
+    /// </summary>
+    Dictionary<string, object> GetParameters();
+    
+    /// <summary>
+    /// Update strategy parameters from configuration
+    /// </summary>
+    void SetParameters(Dictionary<string, object> parameters);
+}
+```
+
+### **File 2: `src/NT8.Core/Common/Models/StrategyMetadata.cs`**
+```csharp
+namespace NT8.Core.Common.Models;
+
+/// <summary>
+/// Strategy metadata - describes strategy capabilities and requirements
+/// </summary>
+public record StrategyMetadata(
+    string Name,
+    string Description,
+    string Version,
+    string Author,
+    string[] Symbols,
+    int RequiredBars
+);
+
+/// <summary>
+/// Strategy configuration passed during initialization
+/// </summary>
+public record StrategyConfig(
+    string Name,
+    string Symbol,
+    Dictionary<string, object> Parameters,
+    RiskConfig RiskSettings,
+    SizingConfig SizingSettings
+);
+```
+
+### **File 3: `src/NT8.Core/Common/Models/StrategyIntent.cs`**
+```csharp
+namespace NT8.Core.Common.Models;
+
+/// <summary>
+/// Strategy trading intent - what the strategy wants to do
+/// This is the output of strategy logic, input to risk management
+/// </summary>
+public record StrategyIntent(
+    string Symbol,
+    OrderSide Side,
+    OrderType EntryType,
+    double? LimitPrice,
+    int StopTicks,
+    int? TargetTicks,
+    double Confidence,      // 0.0 to 1.0 - strategy confidence level
+    string Reason,          // Human-readable reason for trade
+    Dictionary<string, object> Metadata  // Additional strategy-specific data
+)
+{
+    /// <summary>
+    /// Unique identifier for this intent
+    /// </summary>
+    public string IntentId { get; init; } = Guid.NewGuid().ToString();
+    
+    /// <summary>
+    /// Timestamp when intent was generated
+    /// </summary>
+    public DateTime Timestamp { get; init; } = DateTime.UtcNow;
+    
+    /// <summary>
+    /// Validate intent has required fields
+    /// </summary>
+    public bool IsValid() => 
+        !string.IsNullOrEmpty(Symbol) && 
+        StopTicks > 0 && 
+        Confidence is >= 0.0 and <= 1.0 &&
+        Side != OrderSide.Flat &&
+        !string.IsNullOrEmpty(Reason);
+}
+
+/// <summary>
+/// Order side enumeration
+/// </summary>
+public enum OrderSide
+{
+    Buy = 1,
+    Sell = -1,
+    Flat = 0  // Close position
+}
+
+/// <summary>
+/// Order type enumeration
+/// </summary>
+public enum OrderType
+{
+    Market,
+    Limit,
+    StopMarket,
+    StopLimit
+}
+```
+
+### **File 4: `src/NT8.Core/Common/Models/StrategyContext.cs`**
+```csharp
+namespace NT8.Core.Common.Models;
+
+/// <summary>
+/// Context information available to strategies
+/// </summary>
+public record StrategyContext(
+    string Symbol,
+    DateTime CurrentTime,
+    Position CurrentPosition,
+    AccountInfo Account,
+    MarketSession Session,
+    Dictionary<string, object> CustomData
+);
+
+/// <summary>
+/// Current position information
+/// </summary>
+public record Position(
+    string Symbol,
+    int Quantity,
+    double AveragePrice,
+    double UnrealizedPnL,
+    double RealizedPnL,
+    DateTime LastUpdate
+);
+
+/// <summary>
+/// Account information
+/// </summary>
+public record AccountInfo(
+    double Equity,
+    double BuyingPower,
+    double DailyPnL,
+    double MaxDrawdown,
+    DateTime LastUpdate
+);
+
+/// <summary>
+/// Market session information
+/// </summary>
+public record MarketSession(
+    DateTime SessionStart,
+    DateTime SessionEnd,
+    bool IsRth, // Regular Trading Hours
+    string SessionName
+);
+```
+
+### **File 5: `src/NT8.Core/Common/Models/MarketData.cs`**
+```csharp
+namespace NT8.Core.Common.Models;
+
+/// <summary>
+/// Bar data model
+/// </summary>
+public record BarData(
+    string Symbol,
+    DateTime Time,
+    double Open,
+    double High,
+    double Low,
+    double Close,
+    long Volume,
+    TimeSpan BarSize
+);
+
+/// <summary>
+/// Tick data model  
+/// </summary>
+public record TickData(
+    string Symbol,
+    DateTime Time,
+    double Price,
+    int Size,
+    TickType Type
+);
+
+/// <summary>
+/// Order fill model
+/// </summary>
+public record OrderFill(
+    string OrderId,
+    string Symbol,
+    int Quantity,
+    double FillPrice,
+    DateTime FillTime,
+    double Commission,
+    string ExecutionId
+);
+
+public enum TickType
+{
+    Trade,
+    Bid,
+    Ask,
+    Last
+}
+
+/// <summary>
+/// Market data provider interface
+/// </summary>
+public interface IMarketDataProvider
+{
+    /// <summary>
+    /// Subscribe to bar data
+    /// </summary>
+    void SubscribeBars(string symbol, TimeSpan barSize, Action<BarData> onBar);
+    
+    /// <summary>
+    /// Subscribe to tick data
+    /// </summary>
+    void SubscribeTicks(string symbol, Action<TickData> onTick);
+    
+    /// <summary>
+    /// Get historical bars
+    /// </summary>
+    Task<List<BarData>> GetHistoricalBars(string symbol, TimeSpan barSize, int count);
+    
+    /// <summary>
+    /// Get current market price
+    /// </summary>
+    double? GetCurrentPrice(string symbol);
+}
+```
+
+### **File 6: `src/NT8.Core/Risk/IRiskManager.cs`**
+```csharp
+using NT8.Core.Common.Models;
+
+namespace NT8.Core.Risk;
+
+/// <summary>
+/// Risk management interface - validates and potentially modifies trading intents
+/// This is the gatekeeper between strategy signals and order execution
+/// </summary>
+public interface IRiskManager
+{
+    /// <summary>
+    /// Validate order intent against risk parameters
+    /// Returns decision with allow/reject and any modifications
+    /// </summary>
+    RiskDecision ValidateOrder(StrategyIntent intent, StrategyContext context, RiskConfig config);
+    
+    /// <summary>
+    /// Update risk state after order fill
+    /// </summary>
+    void OnFill(OrderFill fill);
+    
+    /// <summary>
+    /// Update risk state with current P&L
+    /// </summary>
+    void OnPnLUpdate(double netPnL, double dayPnL);
+    
+    /// <summary>
+    /// Emergency flatten all positions
+    /// </summary>
+    Task<bool> EmergencyFlatten(string reason);
+    
+    /// <summary>
+    /// Get current risk status for monitoring
+    /// </summary>
+    RiskStatus GetRiskStatus();
+}
+
+/// <summary>
+/// Risk validation result
+/// </summary>
+public record RiskDecision(
+    bool Allow,
+    string? RejectReason,
+    StrategyIntent? ModifiedIntent,  // If risk manager modifies size/price
+    RiskLevel RiskLevel,
+    Dictionary<string, object> RiskMetrics
+);
+
+/// <summary>
+/// Current risk system status
+/// </summary>
+public record RiskStatus(
+    bool TradingEnabled,
+    double DailyPnL,
+    double DailyLossLimit,
+    double MaxDrawdown,
+    int OpenPositions,
+    DateTime LastUpdate,
+    List<string> ActiveAlerts
+);
+
+/// <summary>
+/// Risk level classification
+/// </summary>
+public enum RiskLevel
+{
+    Low,      // Normal trading
+    Medium,   // Elevated caution
+    High,     // Limited trading
+    Critical  // Trading halted
+}
+
+/// <summary>
+/// Risk configuration parameters
+/// </summary>
+public record RiskConfig(
+    double DailyLossLimit,
+    double MaxTradeRisk,
+    int MaxOpenPositions,
+    bool EmergencyFlattenEnabled
+);
+```
+
+### **File 7: `src/NT8.Core/Sizing/IPositionSizer.cs`**
+```csharp
+using NT8.Core.Common.Models;
+
+namespace NT8.Core.Sizing;
+
+/// <summary>
+/// Position sizing interface - determines contract quantity
+/// </summary>
+public interface IPositionSizer
+{
+    /// <summary>
+    /// Calculate position size for trading intent
+    /// </summary>
+    SizingResult CalculateSize(StrategyIntent intent, StrategyContext context, SizingConfig config);
+