blokctl 1.3.0 → 1.4.0

package/dist/scaffold-repo/sdks/csharp/src/Blok.Core/Errors/BlokErrorCategory.cs

@@ -0,0 +1,112 @@
+namespace Blok.Core.Errors;
+
+/// <summary>
+/// The 12 canonical error categories every Blok node error falls into.
+///
+/// <para>Mirrors the proto <c>blok.runtime.v1.ErrorCategory</c> enum
+/// value-for-value and matches the Python <c>BlokErrorCategory</c>, Go
+/// <c>CategoryDependency</c>, Rust <c>BlokErrorCategory::Dependency</c>, and
+/// Java <c>BlokErrorCategory.DEPENDENCY</c> constants. Each category carries a
+/// default HTTP status and retryable hint that authors can override
+/// per-error via the builder.</para>
+/// </summary>
+public enum BlokErrorCategory
+{
+    /// <summary>Input failed schema validation. Default HTTP 400, non-retryable.</summary>
+    Validation,
+    /// <summary>Misconfiguration of the runner / node / environment. Default 500, non-retryable.</summary>
+    Configuration,
+    /// <summary>External dependency unreachable (DB, API). Default 502, retryable.</summary>
+    Dependency,
+    /// <summary>Deadline exceeded. Default 504, retryable.</summary>
+    Timeout,
+    /// <summary>Caller lacks the right role/scope. Default 403, non-retryable.</summary>
+    Permission,
+    /// <summary>Caller exceeded a quota. Default 429, retryable with retry_after_ms.</summary>
+    RateLimit,
+    /// <summary>Resource not found. Default 404, non-retryable.</summary>
+    NotFound,
+    /// <summary>Idempotency violation, concurrent update. Default 409, non-retryable.</summary>
+    Conflict,
+    /// <summary>Caller cancelled before completion. Default 499, non-retryable.</summary>
+    Cancelled,
+    /// <summary>SDK threw without classification — default fallback. Default 500, non-retryable.</summary>
+    Internal,
+    /// <summary>Wire-format / framing / serialization error. Default 502, non-retryable.</summary>
+    Protocol,
+    /// <summary>Payload schema OK but values are unprocessable. Default 422, non-retryable.</summary>
+    Data,
+}
+
+/// <summary>
+/// Per-category default tables and string conversions for
+/// <see cref="BlokErrorCategory"/>. C# enums can't carry data like Java's, so
+/// the lookup tables live as extension methods here.
+/// </summary>
+public static class BlokErrorCategoryExtensions
+{
+    /// <summary>HTTP status conventionally associated with this category.</summary>
+    public static int DefaultHttpStatus(this BlokErrorCategory category) => category switch
+    {
+        BlokErrorCategory.Validation => 400,
+        BlokErrorCategory.Configuration => 500,
+        BlokErrorCategory.Dependency => 502,
+        BlokErrorCategory.Timeout => 504,
+        BlokErrorCategory.Permission => 403,
+        BlokErrorCategory.RateLimit => 429,
+        BlokErrorCategory.NotFound => 404,
+        BlokErrorCategory.Conflict => 409,
+        BlokErrorCategory.Cancelled => 499,
+        BlokErrorCategory.Internal => 500,
+        BlokErrorCategory.Protocol => 502,
+        BlokErrorCategory.Data => 422,
+        _ => 500,
+    };
+
+    /// <summary>Retryable hint conventionally associated with this category.</summary>
+    public static bool DefaultRetryable(this BlokErrorCategory category) => category switch
+    {
+        BlokErrorCategory.Dependency => true,
+        BlokErrorCategory.Timeout => true,
+        BlokErrorCategory.RateLimit => true,
+        _ => false,
+    };
+
+    /// <summary>String form matching the proto enum name (e.g. <c>"DEPENDENCY"</c>).</summary>
+    public static string AsWire(this BlokErrorCategory category) => category switch
+    {
+        BlokErrorCategory.Validation => "VALIDATION",
+        BlokErrorCategory.Configuration => "CONFIGURATION",
+        BlokErrorCategory.Dependency => "DEPENDENCY",
+        BlokErrorCategory.Timeout => "TIMEOUT",
+        BlokErrorCategory.Permission => "PERMISSION",
+        BlokErrorCategory.RateLimit => "RATE_LIMIT",
+        BlokErrorCategory.NotFound => "NOT_FOUND",
+        BlokErrorCategory.Conflict => "CONFLICT",
+        BlokErrorCategory.Cancelled => "CANCELLED",
+        BlokErrorCategory.Internal => "INTERNAL",
+        BlokErrorCategory.Protocol => "PROTOCOL",
+        BlokErrorCategory.Data => "DATA",
+        _ => "INTERNAL",
+    };
+
+    /// <summary>
+    /// Parse a wire string into a category, falling back to <see cref="BlokErrorCategory.Internal"/>
+    /// for unknown values (matches Python/Go/Rust/Java behaviour).
+    /// </summary>
+    public static BlokErrorCategory Parse(string? value) => value switch
+    {
+        "VALIDATION" => BlokErrorCategory.Validation,
+        "CONFIGURATION" => BlokErrorCategory.Configuration,
+        "DEPENDENCY" => BlokErrorCategory.Dependency,
+        "TIMEOUT" => BlokErrorCategory.Timeout,
+        "PERMISSION" => BlokErrorCategory.Permission,
+        "RATE_LIMIT" => BlokErrorCategory.RateLimit,
+        "NOT_FOUND" => BlokErrorCategory.NotFound,
+        "CONFLICT" => BlokErrorCategory.Conflict,
+        "CANCELLED" => BlokErrorCategory.Cancelled,
+        "PROTOCOL" => BlokErrorCategory.Protocol,
+        "DATA" => BlokErrorCategory.Data,
+        _ => BlokErrorCategory.Internal,
+    };
+}

package/dist/scaffold-repo/sdks/csharp/src/Blok.Core/Errors/BlokErrorSeverity.cs

@@ -0,0 +1,40 @@
+namespace Blok.Core.Errors;
+
+/// <summary>
+/// How serious an error is. Mirrors the proto
+/// <c>blok.runtime.v1.ErrorSeverity</c> enum. Default for thrown errors is
+/// <see cref="Error"/>.
+/// </summary>
+public enum BlokErrorSeverity
+{
+    /// <summary>Informational, no action needed.</summary>
+    Info,
+    /// <summary>Recoverable, worth surfacing.</summary>
+    Warn,
+    /// <summary>Standard error level.</summary>
+    Error,
+    /// <summary>Process must terminate.</summary>
+    Fatal,
+}
+
+public static class BlokErrorSeverityExtensions
+{
+    public static string AsWire(this BlokErrorSeverity severity) => severity switch
+    {
+        BlokErrorSeverity.Info => "INFO",
+        BlokErrorSeverity.Warn => "WARN",
+        BlokErrorSeverity.Error => "ERROR",
+        BlokErrorSeverity.Fatal => "FATAL",
+        _ => "ERROR",
+    };
+
+    /// <summary>Parse a wire string, falling back to <see cref="BlokErrorSeverity.Error"/>.</summary>
+    public static BlokErrorSeverity Parse(string? value) => value switch
+    {
+        "INFO" => BlokErrorSeverity.Info,
+        "WARN" => BlokErrorSeverity.Warn,
+        "ERROR" => BlokErrorSeverity.Error,
+        "FATAL" => BlokErrorSeverity.Fatal,
+        _ => BlokErrorSeverity.Error,
+    };
+}

package/dist/scaffold-repo/sdks/csharp/src/Blok.Core/Errors/BuildContextSnapshot.cs

@@ -0,0 +1,168 @@
+using System.Text.Json;
+
+namespace Blok.Core.Errors;
+
+/// <summary>
+/// Bounded slice of inputs + recent vars for the
+/// <c>BlokError.ContextSnapshot</c> field, per master plan §17.6.
+///
+/// <para>Default budget: 4 KB serialized + last-16 vars keys, with
+/// progressive trimming when oversize. <c>inputs</c> is preserved as-is —
+/// it's the most LLM-actionable context. Mirrors Python's
+/// <c>build_context_snapshot</c>, Go's <c>BuildContextSnapshot</c>, Rust's
+/// <c>build_context_snapshot</c>, and Java's <c>BuildContextSnapshot.of</c>.</para>
+/// </summary>
+public static class BuildContextSnapshot
+{
+    private static readonly JsonSerializerOptions JsonOptions = new()
+    {
+        DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.Never,
+    };
+
+    /// <summary>Snapshot of <c>inputs</c> + last-16 vars keys, capped at 4 KB.</summary>
+    public static Dictionary<string, object?> Of(
+        IReadOnlyDictionary<string, object?> inputs,
+        IReadOnlyDictionary<string, object?> vars)
+        => Of(inputs, vars, BlokError.ContextSnapshotMaxBytes, 16);
+
+    /// <summary>
+    /// Customizable variant. <c>maxVarsKeys=0</c> drops vars entirely.
+    /// <c>maxBytes&lt;=0</c> disables byte-budget trimming.
+    /// </summary>
+    public static Dictionary<string, object?> Of(
+        IReadOnlyDictionary<string, object?> inputs,
+        IReadOnlyDictionary<string, object?> vars,
+        int maxBytes,
+        int maxVarsKeys)
+    {
+        var safeInputs = JsonSafeMap(inputs);
+
+        // SortedDictionary gives a deterministic "last N" slice.
+        // Dictionary<TKey,TValue> iteration order is implementation-defined;
+        // tests need determinism. Mirrors Java's TreeMap and Rust's BTreeMap.
+        var sorted = new SortedDictionary<string, object?>(
+            (vars as IDictionary<string, object?>) ?? new Dictionary<string, object?>(vars ?? new Dictionary<string, object?>()));
+        var keys = sorted.Keys.ToList();
+        if (maxVarsKeys >= 0 && keys.Count > maxVarsKeys)
+        {
+            keys = keys.GetRange(keys.Count - maxVarsKeys, maxVarsKeys);
+        }
+
+        var recent = new Dictionary<string, object?>();
+        foreach (var k in keys)
+        {
+            recent[k] = JsonSafe(sorted[k]);
+        }
+
+        var snapshot = new Dictionary<string, object?>
+        {
+            ["inputs"] = safeInputs,
+            ["vars"] = recent,
+        };
+
+        if (maxBytes <= 0) return snapshot;
+        if (EncodedBytes(snapshot) <= maxBytes) return snapshot;
+
+        // Trim from the front (oldest keys) until the snapshot fits.
+        while (keys.Count > 0)
+        {
+            keys.RemoveAt(0);
+            recent = new Dictionary<string, object?>();
+            foreach (var k in keys)
+            {
+                recent[k] = JsonSafe(sorted[k]);
+            }
+            snapshot["vars"] = recent;
+            if (EncodedBytes(snapshot) <= maxBytes) return snapshot;
+        }
+
+        return new Dictionary<string, object?>
+        {
+            ["inputs"] = safeInputs,
+            ["vars"] = new Dictionary<string, object?>(),
+            ["_truncated"] = true,
+        };
+    }
+
+    private static int EncodedBytes(object value)
+    {
+        try
+        {
+            return JsonSerializer.SerializeToUtf8Bytes(value, JsonOptions).Length;
+        }
+        catch
+        {
+            return int.MaxValue;
+        }
+    }
+
+    private static Dictionary<string, object?> JsonSafeMap(IReadOnlyDictionary<string, object?> m)
+    {
+        var output = new Dictionary<string, object?>();
+        if (m is null) return output;
+        foreach (var kv in m)
+        {
+            output[kv.Key] = JsonSafe(kv.Value);
+        }
+        return output;
+    }
+
+    private static object? JsonSafe(object? v)
+    {
+        if (v is null
+            || v is string
+            || v is bool
+            || v is sbyte || v is byte
+            || v is short || v is ushort
+            || v is int || v is uint
+            || v is long || v is ulong
+            || v is float || v is double || v is decimal
+            || v is JsonElement)
+        {
+            return v;
+        }
+
+        if (v is IReadOnlyDictionary<string, object?> readOnlyMap)
+        {
+            return JsonSafeMap(readOnlyMap);
+        }
+
+        if (v is IDictionary<string, object?> map)
+        {
+            var output = new Dictionary<string, object?>();
+            foreach (var kv in map)
+            {
+                output[kv.Key] = JsonSafe(kv.Value);
+            }
+            return output;
+        }
+
+        if (v is System.Collections.IDictionary rawMap)
+        {
+            var output = new Dictionary<string, object?>();
+            foreach (System.Collections.DictionaryEntry e in rawMap)
+            {
+                output[e.Key.ToString() ?? ""] = JsonSafe(e.Value);
+            }
+            return output;
+        }
+
+        if (v is System.Collections.IEnumerable list && v is not string)
+        {
+            var output = new List<object?>();
+            foreach (var x in list) output.Add(JsonSafe(x));
+            return output;
+        }
+
+        // Anything else — try a JSON round-trip; on failure fall back to ToString.
+        try
+        {
+            var json = JsonSerializer.Serialize(v, JsonOptions);
+            return JsonSerializer.Deserialize<object?>(json, JsonOptions);
+        }
+        catch
+        {
+            return v.ToString();
+        }
+    }
+}

package/dist/scaffold-repo/sdks/csharp/src/Blok.Core/Errors/ErrorCategory.cs

@@ -0,0 +1,13 @@
+namespace Blok.Core.Errors;
+
+/// <summary>
+/// ErrorCategory classifies the type of error that occurred.
+/// </summary>
+public enum ErrorCategory
+{
+    Validation,
+    Execution,
+    Configuration,
+    Network,
+    NotFound
+}

package/dist/scaffold-repo/sdks/csharp/src/Blok.Core/Errors/NodeException.cs

@@ -0,0 +1,44 @@
+namespace Blok.Core.Errors;
+
+/// <summary>
+/// NodeException represents a structured error from node execution.
+/// </summary>
+public class NodeException : Exception
+{
+    /// <summary>HTTP-style status code.</summary>
+    public int Code { get; }
+
+    /// <summary>Error category for classification.</summary>
+    public ErrorCategory Category { get; }
+
+    /// <summary>Optional additional details.</summary>
+    public Dictionary<string, object?>? Details { get; }
+
+    public NodeException(string message, int code, ErrorCategory category, Dictionary<string, object?>? details = null)
+        : base($"[{category.ToString().ToUpperInvariant()}] {message}")
+    {
+        Code = code;
+        Category = category;
+        Details = details;
+    }
+
+    /// <summary>Create a validation error (400).</summary>
+    public static NodeException Validation(string message, Dictionary<string, object?>? details = null)
+        => new(message, 400, ErrorCategory.Validation, details);
+
+    /// <summary>Create an execution error (500).</summary>
+    public static NodeException Execution(string message, Dictionary<string, object?>? details = null)
+        => new(message, 500, ErrorCategory.Execution, details);
+
+    /// <summary>Create a configuration error (500).</summary>
+    public static NodeException Configuration(string message, Dictionary<string, object?>? details = null)
+        => new(message, 500, ErrorCategory.Configuration, details);
+
+    /// <summary>Create a network error (502).</summary>
+    public static NodeException Network(string message, Dictionary<string, object?>? details = null)
+        => new(message, 502, ErrorCategory.Network, details);
+
+    /// <summary>Create a not-found error (404).</summary>
+    public static NodeException NotFound(string message, Dictionary<string, object?>? details = null)
+        => new(message, 404, ErrorCategory.NotFound, details);
+}

package/dist/scaffold-repo/sdks/csharp/src/Blok.Core/Logging/LogEntry.cs

@@ -0,0 +1,34 @@
+namespace Blok.Core.Logging;
+
+/// <summary>
+/// A single log entry captured by the Logger.
+/// </summary>
+public class LogEntry
+{
+    public LogLevel Level { get; set; }
+    public string Message { get; set; } = string.Empty;
+    public DateTime Timestamp { get; set; }
+    public Dictionary<string, object?>? Fields { get; set; }
+
+    public override string ToString()
+    {
+        var levelStr = Level switch
+        {
+            LogLevel.Debug => "DEBUG",
+            LogLevel.Info => "INFO",
+            LogLevel.Warn => "WARN",
+            LogLevel.Error => "ERROR",
+            _ => "UNKNOWN"
+        };
+
+        var ts = Timestamp.ToString("O");
+
+        if (Fields is not null && Fields.Count > 0)
+        {
+            var fieldsStr = string.Join(", ", Fields.Select(kv => $"{kv.Key}={kv.Value}"));
+            return $"[{levelStr}] {ts} {Message} {{{fieldsStr}}}";
+        }
+
+        return $"[{levelStr}] {ts} {Message}";
+    }
+}

package/dist/scaffold-repo/sdks/csharp/src/Blok.Core/Logging/LogLevel.cs

@@ -0,0 +1,12 @@
+namespace Blok.Core.Logging;
+
+/// <summary>
+/// Log levels for structured logging.
+/// </summary>
+public enum LogLevel
+{
+    Debug = 0,
+    Info = 1,
+    Warn = 2,
+    Error = 3
+}

package/dist/scaffold-repo/sdks/csharp/src/Blok.Core/Logging/Logger.cs

@@ -0,0 +1,92 @@
+namespace Blok.Core.Logging;
+
+/// <summary>
+/// Logger captures log entries for inclusion in ExecutionResult.logs.
+/// Thread-safe via lock.
+/// </summary>
+public class Logger
+{
+    private readonly List<LogEntry> _entries = new();
+    private readonly object _lock = new();
+    private readonly LogLevel _minLevel;
+
+    public Logger(LogLevel minLevel = LogLevel.Info)
+    {
+        _minLevel = minLevel;
+    }
+
+    private void Log(LogLevel level, string message, Dictionary<string, object?>? fields = null)
+    {
+        if (level < _minLevel) return;
+
+        var entry = new LogEntry
+        {
+            Level = level,
+            Message = message,
+            Timestamp = DateTime.UtcNow,
+            Fields = fields
+        };
+
+        lock (_lock)
+        {
+            _entries.Add(entry);
+        }
+    }
+
+    /// <summary>Log a debug message.</summary>
+    public void Debug(string message) => Log(LogLevel.Debug, message);
+
+    /// <summary>Log a debug message with fields.</summary>
+    public void Debug(string message, Dictionary<string, object?> fields) => Log(LogLevel.Debug, message, fields);
+
+    /// <summary>Log an info message.</summary>
+    public void Info(string message) => Log(LogLevel.Info, message);
+
+    /// <summary>Log an info message with fields.</summary>
+    public void Info(string message, Dictionary<string, object?> fields) => Log(LogLevel.Info, message, fields);
+
+    /// <summary>Log a warning message.</summary>
+    public void Warn(string message) => Log(LogLevel.Warn, message);
+
+    /// <summary>Log a warning message with fields.</summary>
+    public void Warn(string message, Dictionary<string, object?> fields) => Log(LogLevel.Warn, message, fields);
+
+    /// <summary>Log an error message.</summary>
+    public void Error(string message) => Log(LogLevel.Error, message);
+
+    /// <summary>Log an error message with fields.</summary>
+    public void Error(string message, Dictionary<string, object?> fields) => Log(LogLevel.Error, message, fields);
+
+    /// <summary>
+    /// Get all captured log entries.
+    /// </summary>
+    public List<LogEntry> Entries()
+    {
+        lock (_lock)
+        {
+            return new List<LogEntry>(_entries);
+        }
+    }
+
+    /// <summary>
+    /// Get log entries as formatted strings for ExecutionResult.logs.
+    /// </summary>
+    public List<string> Lines()
+    {
+        lock (_lock)
+        {
+            return _entries.Select(e => e.ToString()).ToList();
+        }
+    }
+
+    /// <summary>
+    /// Clear all captured entries.
+    /// </summary>
+    public void Clear()
+    {
+        lock (_lock)
+        {
+            _entries.Clear();
+        }
+    }
+}

package/dist/scaffold-repo/sdks/csharp/src/Blok.Core/Middleware/IMiddleware.cs

@@ -0,0 +1,14 @@
+using Blok.Core.Node;
+
+namespace Blok.Core.Middleware;
+
+/// <summary>
+/// IMiddleware wraps a node handler to add cross-cutting behavior.
+/// </summary>
+public interface IMiddleware
+{
+    /// <summary>
+    /// Wrap a handler and return a new handler with additional behavior.
+    /// </summary>
+    INodeHandler Wrap(INodeHandler next);
+}

package/dist/scaffold-repo/sdks/csharp/src/Blok.Core/Middleware/LoggingMiddleware.cs

@@ -0,0 +1,46 @@
+using System.Diagnostics;
+using System.Text.Json;
+using Blok.Core.Node;
+
+namespace Blok.Core.Middleware;
+
+/// <summary>
+/// LoggingMiddleware logs node execution with timing.
+/// </summary>
+public class LoggingMiddleware : IMiddleware
+{
+    public INodeHandler Wrap(INodeHandler next)
+    {
+        return new LoggingHandler(next);
+    }
+
+    private class LoggingHandler : INodeHandler
+    {
+        private readonly INodeHandler _inner;
+
+        public LoggingHandler(INodeHandler inner)
+        {
+            _inner = inner;
+        }
+
+        public async Task<JsonElement> ExecuteAsync(Types.Context ctx, Dictionary<string, JsonElement> config)
+        {
+            var stopwatch = Stopwatch.StartNew();
+            Console.WriteLine($"[INFO] {DateTime.UtcNow:O} Node execution started workflow={ctx.WorkflowName}");
+
+            try
+            {
+                var result = await _inner.ExecuteAsync(ctx, config);
+                stopwatch.Stop();
+                Console.WriteLine($"[INFO] {DateTime.UtcNow:O} Node execution completed workflow={ctx.WorkflowName} duration_ms={stopwatch.Elapsed.TotalMilliseconds:F2}");
+                return result;
+            }
+            catch (Exception ex)
+            {
+                stopwatch.Stop();
+                Console.WriteLine($"[ERROR] {DateTime.UtcNow:O} Node execution failed workflow={ctx.WorkflowName} duration_ms={stopwatch.Elapsed.TotalMilliseconds:F2} error={ex.Message}");
+                throw;
+            }
+        }
+    }
+}

package/dist/scaffold-repo/sdks/csharp/src/Blok.Core/Middleware/MiddlewareChain.cs

@@ -0,0 +1,35 @@
+using Blok.Core.Node;
+
+namespace Blok.Core.Middleware;
+
+/// <summary>
+/// MiddlewareChain applies a chain of middleware to a handler.
+/// </summary>
+public class MiddlewareChain
+{
+    private readonly List<IMiddleware> _middlewares = new();
+
+    /// <summary>
+    /// Add a middleware to the chain.
+    /// </summary>
+    public MiddlewareChain Use(IMiddleware middleware)
+    {
+        _middlewares.Add(middleware);
+        return this;
+    }
+
+    /// <summary>
+    /// Apply all middleware to the given handler, returning the wrapped handler.
+    /// Middleware is applied in order: first added wraps outermost.
+    /// </summary>
+    public INodeHandler Apply(INodeHandler handler)
+    {
+        var current = handler;
+        // Apply in reverse so that the first middleware added is the outermost wrapper
+        for (int i = _middlewares.Count - 1; i >= 0; i--)
+        {
+            current = _middlewares[i].Wrap(current);
+        }
+        return current;
+    }
+}

package/dist/scaffold-repo/sdks/csharp/src/Blok.Core/Middleware/RecoveryMiddleware.cs

@@ -0,0 +1,63 @@
+using System.Text.Json;
+using Blok.Core.Errors;
+using Blok.Core.Node;
+
+namespace Blok.Core.Middleware;
+
+/// <summary>
+/// RecoveryMiddleware catches exceptions and returns them as error JSON.
+///
+/// <para>Structured exceptions (<see cref="BlokError"/>, <see cref="NodeException"/>)
+/// pass through verbatim so the registry / gRPC servicer can serialize them
+/// losslessly. All other exceptions are wrapped in a recovered JSON shape.</para>
+/// </summary>
+public class RecoveryMiddleware : IMiddleware
+{
+    public INodeHandler Wrap(INodeHandler next)
+    {
+        return new RecoveryHandler(next);
+    }
+
+    private class RecoveryHandler : INodeHandler
+    {
+        private readonly INodeHandler _inner;
+
+        public RecoveryHandler(INodeHandler inner)
+        {
+            _inner = inner;
+        }
+
+        public async Task<JsonElement> ExecuteAsync(Types.Context ctx, Dictionary<string, JsonElement> config)
+        {
+            try
+            {
+                return await _inner.ExecuteAsync(ctx, config);
+            }
+            catch (BlokError)
+            {
+                // Master plan §17 BlokError passes through verbatim — the
+                // registry catches it directly and stashes the typed instance
+                // on `ExecutionResult.Errors` for the gRPC servicer.
+                throw;
+            }
+            catch (NodeException)
+            {
+                // Legacy structured exceptions pass through as-is too.
+                throw;
+            }
+            catch (Exception ex)
+            {
+                Console.WriteLine($"[RECOVERY] Caught exception: {ex.Message}");
+
+                var errorJson = JsonSerializer.Serialize(new
+                {
+                    error = ex.Message,
+                    type = ex.GetType().Name,
+                    recovered = true
+                });
+
+                return JsonDocument.Parse(errorJson).RootElement.Clone();
+            }
+        }
+    }
+}