NEXUS Technical Architecture

UCB1 = Q(s,a) / N(s,a) + C × √(ln(N(s)) / N(s,a))

Where:
  Q(s,a) = Total reward from action a in state s
  N(s,a) = Visit count for action a in state s
  N(s)   = Total visits to state s
  C      = Exploration constant (default: √2 ≈ 1.414)

public interface ITectonicEngine
{
    /// <summary>Runs MCTS search from current state</summary>
    Task<SearchResult> SearchAsync(
        WorldState initialState,
        SearchConfig config,
        CancellationToken ct = default);

    /// <summary>Executes best action and returns new state</summary>
    Task<ExecutionResult> ExecuteBestActionAsync(
        SearchResult search,
        CancellationToken ct = default);
}

public async Task<SearchResult> SearchAsync(
    WorldState initialState, 
    SearchConfig config,
    CancellationToken ct)
{
    var root = new TreeNode(initialState);
    
    for (int i = 0; i < config.MaxIterations; i++)
    {
        // 1. SELECT - Find promising leaf using UCB1
        var leaf = SelectLeaf(root);
        
        // 2. EXPAND - Generate new actions via Planner
        var actions = await _planner.ProposeActionsAsync(
            leaf.State, ct);
        ExpandNode(leaf, actions);
        
        // 3. SIMULATE - Predict outcomes via Simulator
        var outcomes = await _simulator.PredictOutcomesAsync(
            leaf.State, actions, ct);
        
        // 4. EVALUATE - Score outcomes via Critic
        var scores = await _critic.EvaluateAsync(
            outcomes, ct);
        
        // 5. BACKPROPAGATE - Update tree statistics
        Backpropagate(leaf, scores);
    }
    
    return new SearchResult(root, GetBestPath(root));
}

public interface IPlannerAgent
{
    /// <summary>
    /// Generates diverse action candidates for the current state.
    /// Returns 3-5 actions balancing exploration and exploitation.
    /// </summary>
    Task<IReadOnlyList<ProposedAction>> ProposeActionsAsync(
        WorldState currentState,
        CancellationToken ct = default);

    /// <summary>
    /// Refines actions based on Critic feedback.
    /// </summary>
    Task<ProposedAction> RefineActionAsync(
        ProposedAction original,
        CriticFeedback feedback,
        CancellationToken ct = default);
}

public record ProposedAction(
    string Id,
    string Description,
    ActionType Type,
    string ToolName,
    Dictionary<string, object> Parameters,
    float Confidence,
    string Rationale,
    ActionCategory Category
);

public enum ActionCategory
{
    Safe,       // Low risk, incremental progress
    Risky,      // Higher risk, potential breakthrough
    Creative,   // Novel approach, unexplored
    Fallback    // Recovery action if others fail
}

public async Task<IReadOnlyList<ProposedAction>> ProposeActionsAsync(
    WorldState state,
    CancellationToken ct)
{
    var actions = new List<ProposedAction>();
    
    // Generate diverse candidates with different temperatures
    var tasks = new[]
    {
        GenerateWithCategory(ActionCategory.Safe, 0.3f, state, ct),
        GenerateWithCategory(ActionCategory.Risky, 0.9f, state, ct),
        GenerateWithCategory(ActionCategory.Creative, 1.2f, state, ct),
        GenerateWithCategory(ActionCategory.Fallback, 0.5f, state, ct)
    };
    
    var results = await Task.WhenAll(tasks);
    actions.AddRange(results.Where(a => a != null)!);
    
    // Deduplicate similar actions
    return DeduplicateActions(actions);
}

public interface ISimulatorAgent
{
    /// <summary>
    /// Predicts outcomes of actions without executing them.
    /// Uses hybrid approach: LLM + rules + sandbox.
    /// </summary>
    Task<IReadOnlyList<SimulatedOutcome>> PredictOutcomesAsync(
        WorldState currentState,
        IReadOnlyList<ProposedAction> actions,
        CancellationToken ct = default);

    /// <summary>
    /// Runs action in isolated sandbox for accurate prediction.
    /// </summary>
    Task<SimulatedOutcome> SandboxExecuteAsync(
        ProposedAction action,
        IWorldModel sandbox,
        CancellationToken ct = default);
}

public record SimulatedOutcome(
    string ActionId,
    WorldState PredictedState,
    float SuccessProbability,
    float Confidence,
    List<SideEffect> SideEffects,
    SimulationMethod Method,
    TimeSpan EstimatedDuration,
    string Reasoning
);

public record SideEffect(
    string Description,
    SideEffectType Type,      // Reversible, Irreversible, Unknown
    float Probability,
    string[] AffectedResources
);

public async Task<SimulatedOutcome> PredictSingleAsync(
    WorldState state,
    ProposedAction action,
    CancellationToken ct)
{
    // Strategy 1: Check rule-based predictions first (fast)
    if (_ruleEngine.CanPredict(action.Type))
    {
        return _ruleEngine.Predict(state, action);
    }
    
    // Strategy 2: Use sandbox if available (accurate)
    if (_worldModelFactory.CanCreateSandbox(action.Type))
    {
        await using var sandbox = await _worldModelFactory
            .CreateSandboxAsync(state, ct);
        return await SandboxExecuteAsync(action, sandbox, ct);
    }
    
    // Strategy 3: Fall back to LLM prediction (flexible)
    return await _llmPredictor.PredictAsync(state, action, ct);
}

public interface ICriticAgent
{
    /// <summary>
    /// Evaluates simulated outcomes and returns scores for MCTS.
    /// Higher scores indicate better actions.
    /// </summary>
    Task<IReadOnlyList<CriticEvaluation>> EvaluateAsync(
        IReadOnlyList<SimulatedOutcome> outcomes,
        CancellationToken ct = default);

    /// <summary>
    /// Provides detailed feedback for action refinement.
    /// </summary>
    Task<CriticFeedback> GetFeedbackAsync(
        SimulatedOutcome outcome,
        CancellationToken ct = default);
}

public async Task<CriticEvaluation> EvaluateSingleAsync(
    SimulatedOutcome outcome,
    CancellationToken ct)
{
    // Score across multiple dimensions
    var dimensions = new Dictionary<string, (float score, float weight)>
    {
        ["progress"] = (ScoreProgress(outcome), 0.35f),
        ["safety"] = (ScoreSafety(outcome), 0.30f),
        ["efficiency"] = (ScoreEfficiency(outcome), 0.20f),
        ["reversibility"] = (ScoreReversibility(outcome), 0.15f)
    };
    
    // Calculate weighted score
    var weightedScore = dimensions.Sum(d => d.Value.score * d.Value.weight);
    
    // Generate improvement suggestions via LLM
    var suggestions = await GenerateSuggestionsAsync(outcome, dimensions, ct);
    
    return new CriticEvaluation(
        outcome.ActionId,
        weightedScore,
        dimensions.ToDictionary(d => d.Key, d => d.Value.score),
        suggestions,
        DetermineVerdict(weightedScore)
    );
}

public record CriticEvaluation(
    string ActionId,
    float OverallScore,              // 0.0 to 1.0
    Dictionary<string, float> DimensionScores,
    List<string> Suggestions,
    Verdict Verdict
);

public enum Verdict
{
    StrongApprove,   // Score >= 0.85
    Approve,         // Score >= 0.70
    Neutral,         // Score >= 0.50
    Caution,         // Score >= 0.30
    Reject           // Score < 0.30
}

public interface ISentinelMcp
{
    /// <summary>Lists all available MCP tools</summary>
    Task<IReadOnlyList<ToolDefinition>> ListToolsAsync(
        CancellationToken ct = default);

    /// <summary>Executes a tool with given parameters</summary>
    Task<ToolResult> ExecuteToolAsync(
        string toolName,
        Dictionary<string, object> parameters,
        CancellationToken ct = default);

    /// <summary>Checks if tool execution is permitted</summary>
    Task<bool> CanExecuteAsync(
        string toolName,
        SecurityContext context,
        CancellationToken ct = default);
}

public async Task<ToolResult> ExecuteToolAsync(
    string toolName,
    Dictionary<string, object> parameters,
    CancellationToken ct)
{
    // 1. Validate tool exists
    var tool = _tools.GetOrDefault(toolName)
        ?? throw new ToolNotFoundException(toolName);
    
    // 2. Security check
    if (!await _security.AuthorizeAsync(tool, _context, ct))
        throw new UnauthorizedToolAccessException(toolName);
    
    // 3. Validate parameters
    var validated = tool.Schema.Validate(parameters);
    
    // 4. Execute with timeout
    using var cts = CancellationTokenSource
        .CreateLinkedTokenSource(ct);
    cts.CancelAfter(tool.Timeout);
    
    var result = await tool.ExecuteAsync(validated, cts.Token);
    
    // 5. Audit log
    await _audit.LogAsync(new ToolExecutionLog
    {
        Tool = toolName,
        Parameters = parameters,
        Result = result,
        Timestamp = DateTime.UtcNow
    });
    
    return result;
}

public interface IWorldModel : IAsyncDisposable
{
    /// <summary>Current state of the world</summary>
    WorldState CurrentState { get; }
    
    /// <summary>Unique identifier for this world instance</summary>
    string WorldId { get; }

    /// <summary>Executes action and returns new state</summary>
    Task<WorldState> ExecuteAsync(
        ProposedAction action,
        CancellationToken ct = default);

    /// <summary>Creates a checkpoint of current state</summary>
    Task<string> CheckpointAsync(
        string? label = null,
        CancellationToken ct = default);

    /// <summary>Restores state from a checkpoint</summary>
    Task RestoreAsync(
        string checkpointId,
        CancellationToken ct = default);

    /// <summary>Forks world into independent copy</summary>
    Task<IWorldModel> ForkAsync(
        CancellationToken ct = default);
}

public record WorldState
{
    public required string WorldId { get; init; }
    public required WorldType Type { get; init; }
    public required DateTime Timestamp { get; init; }
    
    // File system state
    public ImmutableDictionary<string, FileEntry> Files { get; init; }
    
    // Process state
    public ImmutableList<ProcessInfo> Processes { get; init; }
    
    // Network state
    public NetworkState Network { get; init; }
    
    // Environment variables
    public ImmutableDictionary<string, string> Environment { get; init; }
    
    // Custom typed state per world type
    public ImmutableDictionary<string, JsonElement> Custom { get; init; }
}

public enum WorldType
{
    Docker,        // Containerized environment
    Browser,       // Headless browser sandbox
    FileSystem,    // Virtual file system
    Database,      // Database sandbox
    Composite      // Multiple types combined
}

public async Task<string> CheckpointAsync(
    string? label,
    CancellationToken ct)
{
    var checkpointId = $"cp_{Guid.NewGuid():N}";
    
    // Commit container state to image
    await _docker.Containers.CommitContainerChangesAsync(
        new CommitContainerChangesParameters
        {
            ContainerID = _containerId,
            RepositoryName = $"nexus-checkpoint/{WorldId}",
            Tag = checkpointId
        }, ct);
    
    // Store metadata
    _checkpoints[checkpointId] = new CheckpointMeta
    {
        Id = checkpointId,
        Label = label,
        State = CurrentState,
        CreatedAt = DateTime.UtcNow,
        ParentId = _currentCheckpoint
    };
    
    _currentCheckpoint = checkpointId;
    return checkpointId;
}

public interface IRequestHandler<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    /// <summary>Order in the chain (lower = earlier)</summary>
    int Order { get; }
    
    /// <summary>Whether this handler can process the request</summary>
    bool CanHandle(TRequest request);
    
    /// <summary>Process request and optionally call next handler</summary>
    Task<TResponse> HandleAsync(
        TRequest request,
        Func<TRequest, Task<TResponse>> next,
        CancellationToken ct = default);
}

public interface IOrchestrator
{
    Task<TResponse> ExecuteAsync<TRequest, TResponse>(
        TRequest request,
        CancellationToken ct = default)
        where TRequest : IRequest<TResponse>;
}

public class Orchestrator : IOrchestrator
{
    private readonly IServiceProvider _services;
    private readonly ILogger<Orchestrator> _logger;

    public async Task<TResponse> ExecuteAsync<TRequest, TResponse>(
        TRequest request,
        CancellationToken ct)
        where TRequest : IRequest<TResponse>
    {
        // Get all handlers, ordered by priority
        var handlers = _services
            .GetServices<IRequestHandler<TRequest, TResponse>>()
            .OrderBy(h => h.Order)
            .ToList();

        // Build the chain
        Func<TRequest, Task<TResponse>> chain = _ => 
            Task.FromException<TResponse>(
                new NoHandlerException(typeof(TRequest)));

        // Reverse iterate to build from end to start
        foreach (var handler in handlers.AsEnumerable().Reverse())
        {
            var next = chain;
            chain = req => handler.HandleAsync(req, next, ct);
        }

        return await chain(request);
    }
}

public class ValidationHandler<TRequest, TResponse> 
    : IRequestHandler<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    private readonly IValidator<TRequest> _validator;
    
    public int Order => 100; // Run early
    public bool CanHandle(TRequest request) => true;

    public async Task<TResponse> HandleAsync(
        TRequest request,
        Func<TRequest, Task<TResponse>> next,
        CancellationToken ct)
    {
        var result = await _validator.ValidateAsync(request, ct);
        
        if (!result.IsValid)
            throw new ValidationException(result.Errors);
        
        return await next(request);
    }
}

// Commands (Write operations)
public interface ICommand<TResult> { }

public record ExecuteActionCommand(
    string TaskId,
    ProposedAction Action,
    string RequestedBy
) : ICommand<ActionResult>;

public record CreateTaskCommand(
    string Description,
    TaskPriority Priority,
    Dictionary<string, object> Parameters
) : ICommand<TaskCreatedResult>;

// Queries (Read operations)
public interface IQuery<TResult> { }

public record GetTaskQuery(
    string TaskId
) : IQuery<TaskDetails>;

public record SearchHistoryQuery(
    string? TaskId,
    DateTime? FromDate,
    DateTime? ToDate,
    int Page = 1,
    int PageSize = 20
) : IQuery<PagedResult<HistoryEntry>>;

public interface IMediator
{
    /// <summary>Sends a command for execution</summary>
    Task<TResult> SendAsync<TResult>(
        ICommand<TResult> command, 
        CancellationToken ct = default);
    
    /// <summary>Executes a query and returns results</summary>
    Task<TResult> QueryAsync<TResult>(
        IQuery<TResult> query, 
        CancellationToken ct = default);
}

// Event generated by command
public record ActionExecutedEvent(
    Guid ExecutionId,
    string TaskId,
    ActionType ActionType,
    bool Success,
    DateTime Timestamp
) : IDomainEvent;

// Event handler updates read model
public class ActionExecutedEventHandler : IEventHandler<ActionExecutedEvent>
{
    private readonly IReadStore _readStore;
    
    public async Task HandleAsync(ActionExecutedEvent @event, CancellationToken ct)
    {
        // Update denormalized read model
        await _readStore.UpsertAsync(new HistoryEntry
        {
            Id = @event.ExecutionId.ToString(),
            TaskId = @event.TaskId,
            ActionType = @event.ActionType.ToString(),
            Success = @event.Success,
            Timestamp = @event.Timestamp
        }, ct);
    }
}