npm - blokctl - Versions diffs - 1.3.0 → 1.4.0 - Mend

blokctl 1.3.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (685) hide show

package/dist/scaffold-repo/sdk/javascript/test.html ADDED Viewed

@@ -0,0 +1,68 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Test NanoSDK</title>
+    <script src="/sdk/javascript/nanosdk.min.js"></script>
+  </head>
+  <body>
+    <div id="output"></div>
+    <script type="module">
+      async function runTests() {
+        const host = "http://localhost:4000";
+        const token = "";
+        const requests = [
+          {
+            nodeName: "api_call",
+            type: "python3",
+            inputs: {
+              url: "https://countriesnow.space/api/v0.1/countries/capital",
+              method: "GET",
+              headers: {
+                "Content-Type": "application/json",
+              },
+              responseType: "application/json",
+            },
+          },
+          {
+            nodeName: "@blok/api-call",
+            type: "nodejs",
+            inputs: {
+              url: "https://catfact.ninja/fact",
+              method: "GET",
+              headers: {
+                "Content-Type": "application/json",
+              },
+              responseType: "application/json",
+            },
+          },
+        ];
+        const client = new NanoSDK().createHttpClient(host, token);
+        for (const request of requests) {
+          try {
+            const response = await client[request.type](
+              request.nodeName,
+              request.inputs,
+            );
+            const outputDiv = document.getElementById("output");
+            const pre = document.createElement("pre");
+            pre.textContent = `Response for ${request.inputs.url}:\n${JSON.stringify(response, null, 2)}`;
+            pre.style.overflow = "auto";
+            pre.style.maxHeight = "300px";
+            pre.style.border = "1px solid #ccc";
+            pre.style.padding = "10px";
+            pre.style.backgroundColor = "#f9f9f9";
+            outputDiv.appendChild(pre);
+          } catch (error) {
+            console.error(`Error for ${request.inputs.url}:`, error.message);
+          }
+        }
+      }
+      runTests();
+    </script>
+  </body>
+</html>

package/dist/scaffold-repo/sdks/CLAUDE.md ADDED Viewed

@@ -0,0 +1,67 @@
+# Multi-Language SDKs
+Since v0.5, all SDKs reach the runner over **gRPC** — `HttpRuntimeAdapter` and the
+`POST /execute` HTTP path were removed together with the `RUNTIME_TRANSPORT=http`
+opt-in. SDK processes still expose `GET /health` for orchestrator readiness
+probes, but the runner itself only speaks gRPC.
+## gRPC Contract
+Service: `blok.runtime.v1.NodeRuntime/Execute`. The canonical proto schema is
+[`proto/blok/runtime/v1/runtime.proto`](../proto/blok/runtime/v1/runtime.proto);
+every SDK + the runner keep a copy at their own path, kept in lock-step by
+`bun run proto:sync` (and gated by `proto:check` in CI — edit the canonical file
+only). Each SDK serves a Cap'n Proto–style
+binary `ExecuteRequest` and returns an `ExecuteResponse` carrying the same
+fields as the legacy HTTP `ExecutionResult` (`success`, `data`, `errors`,
+`logs`, `metrics`, `vars`).
+**GET /health** → `{ "status": "healthy" }` (informational; the CLI uses a
+TCP-connect probe against the gRPC port, not this endpoint).
+## Default gRPC Ports
+Go: 10001, Rust: 10002, Java: 10003, C#: 10004, PHP: 10005, Ruby: 10006, Python3: 10007.
+Convention: gRPC port = legacy HTTP port + 1000.
+## Cross-runtime E2E + CI gate
+[`tests/e2e/cross-runtime/`](../tests/e2e/cross-runtime) proves all 7 runtimes
+serve the gRPC contract and a single chain threads `ctx` through every language.
+Two ways to run it:
+- **Docker (CI):** `docker compose -f tests/e2e/cross-runtime/docker-compose.yml up -d --build`
+  then `BLOK_E2E_REQUIRE_ALL=1 bun tests/e2e/cross-runtime/spec-b-typed-e2e.ts`.
+  The compose builds each SDK in gRPC mode on its convention port (10001–10007).
+- **Host toolchains:** `bash tests/e2e/cross-runtime/run-spec-b-e2e.sh` (boots on
+  2000x to avoid clashing with a local dev stack; runs against whatever is up).
+The `.github/workflows/cross-runtime.yml` job runs the Docker path on every PR
+to `main` with `BLOK_E2E_REQUIRE_ALL=1` — a broken runtime build fails the gate
+instead of silently dropping out of the matrix.
+## SDK Node Pattern
+Each SDK registers nodes with a language-specific handler interface:
+- **Go**: `NodeHandler` interface with `Execute(ctx, config) (interface{}, error)`
+- **Rust**: `NodeHandler` trait with `async fn execute(&self, ctx, config) -> Result<Value>`
+- **Python3**: `@node` decorator on functions with Pydantic model type hints; auto-discovered from `BLOK_NODES_DIR`
+- **Java**: `NodeHandler` interface with `execute(Context ctx, Map config)`
+- **C#**: `INodeHandler` interface
+- **PHP**: `NodeHandler` interface
+- **Ruby**: Handler module
+User nodes live in `runtimes/{lang}/nodes/` within projects, registered into the same runtime as the built-in nodes — no manual wiring. The CLI handles every language by one of two models:
+- **Dynamic (`BLOK_NODES_DIR` fs-scan at boot):** **Python** (`@node` decorator), **Ruby** (subclass `Blok::Node::NodeHandler`, discovered via a `self.inherited` registry in `lib/blok/node/discovery.rb`), **PHP** (`implements NodeHandler`, globbed + `require_once` in `bin/serve.php`). The CLI sets `BLOK_NODES_DIR` to `runtimes/<lang>/nodes/` on dev-spawn + in supervisord.
+- **Compiled (codegen a registration shim before the build):** **Go** (`func Register(registry)` → `cmd/server/register_user_nodes.go`), **Rust** (`pub fn register(registry)` → `src/user_nodes/mod.rs`), **C#** (`: INodeHandler` → `UserNodeRegistry.cs`), **Java** (`implements NodeHandler` → `UserNodeRegistry.java`). `generateXxxNodeRegistry` (in `packages/cli/src/services/runtime-setup.ts`) copies each node's sources into the build module + generates the shim, regenerated on every `blokctl dev`. Go/Rust/C# recompile on boot (`go run`/`cargo run`/`dotnet run`); Java boots a prebuilt jar so dev runs `mvn package` after codegen. Each SDK ships a committed no-op default shim so the pristine SDK compiles in CI with zero user nodes.
+## Adding a New SDK Language
+1. Implement the `blok.runtime.v1.NodeRuntime/Execute` gRPC service against the canonical proto `proto/blok/runtime/v1/runtime.proto` (add your SDK's copy path to `scripts/sync-proto.ts` so `proto:sync`/`proto:check` keep it in lock-step)
+2. Decode the binary `ExecuteRequest`, route to the registered node handler by `node.name`, and return an `ExecuteResponse`
+3. Bind a `GET /health` HTTP endpoint for orchestrator readiness probes (the CLI's primary check is a TCP-connect against the gRPC port)
+4. Register a `GrpcRuntimeAdapter` in `core/runner/src/Configuration.ts` (per-kind block in `initializeRuntimeRegistry`) with the new kind + gRPC port env var
+5. Add the `RuntimeKind` value to `core/runner/src/adapters/RuntimeAdapter.ts`
+6. Add `runtime.{lang}` to `NodeTypeSchema` in `core/workflow-helper/src/types/StepOpts.ts`

package/dist/scaffold-repo/sdks/csharp/.dockerignore ADDED Viewed

@@ -0,0 +1,7 @@
+**/bin/
+**/obj/
+**/out/
+**/.vs/
+**/.idea/
+*.user
+*.suo

package/dist/scaffold-repo/sdks/csharp/Blok.Core.sln ADDED Viewed

@@ -0,0 +1,24 @@
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 17
+VisualStudioVersion = 17.0.31903.59
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Blok.Core", "src\Blok.Core\Blok.Core.csproj", "{A1B2C3D4-E5F6-7890-AB12-CD34EF567890}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Blok.Core.Tests", "tests\Blok.Core.Tests\Blok.Core.Tests.csproj", "{B2C3D4E5-F6A7-8901-BC23-DE45FA678901}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Any CPU = Debug|Any CPU
+		Release|Any CPU = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{A1B2C3D4-E5F6-7890-AB12-CD34EF567890}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{A1B2C3D4-E5F6-7890-AB12-CD34EF567890}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{A1B2C3D4-E5F6-7890-AB12-CD34EF567890}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{A1B2C3D4-E5F6-7890-AB12-CD34EF567890}.Release|Any CPU.Build.0 = Release|Any CPU
+		{B2C3D4E5-F6A7-8901-BC23-DE45FA678901}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{B2C3D4E5-F6A7-8901-BC23-DE45FA678901}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{B2C3D4E5-F6A7-8901-BC23-DE45FA678901}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{B2C3D4E5-F6A7-8901-BC23-DE45FA678901}.Release|Any CPU.Build.0 = Release|Any CPU
+	EndGlobalSection
+EndGlobal

package/dist/scaffold-repo/sdks/csharp/Dockerfile ADDED Viewed

@@ -0,0 +1,42 @@
+# Build stage
+# .NET 10 SDK — the projects target net10.0 (sdk:9.0 fails with NETSDK1045).
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /src
+# Copy solution and project files first for layer caching
+COPY Blok.Core.sln ./
+COPY src/Blok.Core/Blok.Core.csproj src/Blok.Core/
+COPY tests/Blok.Core.Tests/Blok.Core.Tests.csproj tests/Blok.Core.Tests/
+RUN dotnet restore
+# Copy all source code
+COPY . .
+# Build and publish
+RUN dotnet publish src/Blok.Core/Blok.Core.csproj \
+    -c Release \
+    -o /app/publish \
+    --no-restore
+# Runtime stage
+FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS runtime
+WORKDIR /app
+# Create non-root user
+RUN addgroup -S appgroup && adduser -S appuser -G appgroup
+USER appuser
+COPY --from=build /app/publish .
+ENV ASPNETCORE_URLS=http://+:8080
+ENV PORT=8080
+ENV GRPC_PORT=10004
+ENV Logging__LogLevel__Microsoft.AspNetCore=Warning
+# HTTP port (informational /health) + gRPC port (the runner only speaks gRPC).
+EXPOSE 8080 10004
+HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
+    CMD wget --no-verbose --tries=1 --spider http://127.0.0.1:8080/health || exit 1
+ENTRYPOINT ["dotnet", "Blok.Core.dll"]

package/dist/scaffold-repo/sdks/csharp/README.md ADDED Viewed

@@ -0,0 +1,138 @@
+# Blok.Core - C# SDK for Blok
+C# SDK for building workflow nodes in the Blok blok framework. Each node runs as a Docker container exposing `POST /execute` and `GET /health` endpoints.
+## Install
+```bash
+dotnet add package Blok.Core
+```
+## Quick Start
+Create a custom node by implementing `INodeHandler`:
+```csharp
+using System.Text.Json;
+using Blok.Core.Node;
+using Blok.Core.Types;
+public class GreetNode : INodeHandler
+{
+    public Task<JsonElement> ExecuteAsync(Context ctx, Dictionary<string, JsonElement> config)
+    {
+        var name = ctx.Request.BodyString("name") ?? "World";
+        var result = JsonSerializer.Serialize(new { message = $"Hello, {name}!" });
+        return Task.FromResult(JsonDocument.Parse(result).RootElement.Clone());
+    }
+}
+```
+Register and start the server:
+```csharp
+using Blok.Core.Config;
+using Blok.Core.Node;
+using Blok.Core.Server;
+var registry = new NodeRegistry();
+registry.Register("greet", new GreetNode());
+await RuntimeServer.Run(registry);
+```
+## Configuration
+Configuration is loaded from environment variables:
+| Variable      | Default   | Description               |
+|---------------|-----------|---------------------------|
+| `PORT`        | `8080`    | Server port               |
+| `HOST`        | `0.0.0.0` | Bind address             |
+| `VERSION`     | `1.0.0`   | Runtime version string   |
+| `LOG_LEVEL`   | `INFO`    | DEBUG, INFO, WARN, ERROR |
+| `ENABLE_CORS` | `false`   | Enable CORS headers      |
+Or configure programmatically:
+```csharp
+var config = new ServerConfig
+{
+    Port = 9090,
+    Version = "2.0.0",
+    EnableCors = true
+};
+await RuntimeServer.Run(registry, config);
+```
+## Middleware
+Add cross-cutting behavior with middleware:
+```csharp
+using Blok.Core.Middleware;
+var chain = new MiddlewareChain()
+    .Use(new RecoveryMiddleware())
+    .Use(new LoggingMiddleware());
+var wrappedHandler = chain.Apply(myHandler);
+```
+Built-in middleware:
+- **LoggingMiddleware** - Logs execution timing
+- **RecoveryMiddleware** - Catches unhandled exceptions
+## Schema Validation
+Validate JSON data against schemas:
+```csharp
+using Blok.Core.Validation;
+var validator = new SchemaValidator();
+var schema = JsonDocument.Parse(@"{
+    ""type"": ""object"",
+    ""required"": [""name"", ""email""],
+    ""properties"": {
+        ""name"": { ""type"": ""string"", ""minLength"": 1 },
+        ""email"": { ""type"": ""string"" }
+    }
+}").RootElement;
+var errors = validator.Validate(data, schema);
+```
+## Testing
+Use `MockContextBuilder` and `TestNodeRunner` for unit tests:
+```csharp
+using Blok.Core.Testing;
+var ctx = new MockContextBuilder()
+    .WithBody(new { name = "Blok" })
+    .WithVar("key", "value")
+    .WithEnv("API_KEY", "test-key")
+    .Build();
+var runner = new TestNodeRunner();
+runner.Register("my-node", new MyNode());
+var result = await runner.ExecuteAsync("my-node", ctx);
+```
+## Docker
+```bash
+docker build -t my-blok .
+docker run -p 8080:8080 my-blok
+```
+## Endpoints
+- `POST /execute` - Execute a node (JSON body: `ExecutionRequest` -> `ExecutionResult`)
+- `GET /health` - Health check (returns `HealthStatus`)
+## License
+MIT

package/dist/scaffold-repo/sdks/csharp/proto/blok/runtime/v1/runtime.proto ADDED Viewed

@@ -0,0 +1,302 @@
+// Blok Runtime v1 — the wire contract between the TypeScript runner and SDK
+// servers (Python, Go, Rust, Java, C#, PHP, Ruby).
+//
+// Single source of truth for cross-language interop. Generated stubs in each
+// SDK are derived from this file via `make proto`.
+//
+// Stability: `blok.runtime.v1` is additive-only. CI runs `buf breaking` to
+// reject backward-incompatible changes. Breaking changes go to `v2`, served
+// alongside `v1` during migration.
+syntax = "proto3";
+package blok.runtime.v1;
+option go_package          = "github.com/nickincloud/blok-go/genpb/blok/runtime/v1;runtimev1";
+option java_package        = "com.blok.runtime.v1";
+option java_multiple_files = true;
+option csharp_namespace    = "Blok.Runtime.V1";
+option php_namespace       = "Blok\\Runtime\\V1";
+option ruby_package        = "Blok::Runtime::V1";
+import "google/protobuf/timestamp.proto";
+// =============================================================================
+// Service
+// =============================================================================
+// NodeRuntime is the contract every Blok SDK exposes. One service handles
+// three responsibilities:
+//   1. Run a node (Execute / ExecuteStream)
+//   2. Tell the runner which nodes it can run (ListNodes)
+//   3. Tell the runner if it is alive (Health)
+service NodeRuntime {
+  // Run a node and return its result. Unary, deadline-driven.
+  rpc Execute       (ExecuteRequest)   returns (ExecuteResponse);
+  // Run a node and stream events back as it executes (logs, progress, partial
+  // results, then a final ExecuteResponse). Optional capability — SDKs that
+  // don't implement it should return UNIMPLEMENTED.
+  rpc ExecuteStream (ExecuteRequest)   returns (stream ExecuteEvent);
+  // Health check (wire-compatible with grpc.health.v1.Health/Check).
+  rpc Health        (HealthRequest)    returns (HealthResponse);
+  // Discover registered nodes and their schemas (drives Studio + OpenAPI gen).
+  rpc ListNodes     (ListNodesRequest) returns (ListNodesResponse);
+}
+// =============================================================================
+// Execute envelope (the "what we send to a node")
+// =============================================================================
+message ExecuteRequest {
+  // Identification: which node, what type, what version.
+  NodeRef        node     = 1;
+  // The node's own resolved inputs. Already mapped (js/, ${...} resolved).
+  // Bytes-encoded JSON: SDKs JSON-decode lazily. NEVER wrapped in {inputs:...}.
+  bytes          inputs   = 2;
+  // Where in the workflow this node sits.
+  StepInfo       step     = 3;
+  // The originating workflow trigger (read-only context for nodes).
+  TriggerInfo    trigger  = 4;
+  // Mutable state: previous step output, persistent vars, env mirror.
+  RuntimeState   state    = 5;
+  // Identity of the parent workflow run.
+  WorkflowInfo   workflow = 6;
+  // Per-call options (deadline, streaming opt-in).
+  ExecuteOptions options  = 7;
+}
+message NodeRef {
+  string name    = 1;   // e.g. "tutorial-store"
+  string type    = 2;   // "runtime.python3"
+  string version = 3;   // optional pin, e.g. "1.0.0"
+}
+message StepInfo {
+  string name  = 1;     // step name in workflow
+  int32  index = 2;     // 0-based index in current branch
+  int32  total = 3;     // total steps in current branch
+  int32  depth = 4;     // 0 = top-level; 1+ = nested in flow node (if-else)
+}
+message TriggerInfo {
+  // Snapshot of the trigger that started the workflow. Read-only for nodes.
+  bytes  body          = 1;            // raw bytes; encoding signaled in headers
+  map<string, string> headers = 2;
+  map<string, string> params  = 3;
+  map<string, string> query   = 4;
+  map<string, string> cookies = 5;
+  string method        = 6;
+  string url           = 7;
+  string base_url      = 8;
+  string trigger_kind  = 9;            // "http" | "worker" | "cron" | ...
+}
+message RuntimeState {
+  // Output of the previous step. Named explicitly so LLM-authored nodes stop
+  // confusing it with vars. Bytes-encoded JSON.
+  bytes  previous_output = 1;
+  // Workflow-scoped persistent storage (set_var: true on prior steps).
+  // Bytes-encoded JSON map<string, any>.
+  bytes  vars            = 2;
+  // String→string env mirror.
+  map<string, string> env = 3;
+}
+message WorkflowInfo {
+  string run_id   = 1;
+  string name     = 2;
+  string path     = 3;
+  string version  = 4;
+  google.protobuf.Timestamp started_at = 5;
+}
+message ExecuteOptions {
+  int64 deadline_ms     = 1;       // hard cutoff (also enforced via gRPC deadline)
+  bool  stream_logs     = 2;       // hint: caller wants ExecuteStream events
+  bool  capture_metrics = 3;
+  // Reserved for future routing/affinity hints without bumping schema.
+  map<string, string> hints = 15;
+}
+// =============================================================================
+// Execute response
+// =============================================================================
+message ExecuteResponse {
+  bool      success      = 1;
+  // The node's primary return value. Bytes-encoded JSON.
+  bytes     data         = 2;
+  // Optional content-type override (default "application/json").
+  string    content_type = 3;
+  // Set iff !success. Always populated on failure (see NodeError).
+  NodeError error        = 4;
+  // Vars the node wants persisted (merged into ctx.vars on the runner side).
+  // Optional — most nodes leave this empty and rely on workflow-level set_var.
+  // Bytes-encoded JSON map<string, any>.
+  bytes     vars_delta   = 5;
+  // Tail of logs captured during execution.
+  repeated  LogLine logs = 6;
+  // Resource usage during this call. Populated when capture_metrics=true.
+  Metrics   metrics      = 7;
+}
+// =============================================================================
+// Streaming variant (Phase 5 — opt-in)
+// =============================================================================
+message ExecuteEvent {
+  oneof event {
+    NodeStarted     started  = 1;
+    LogLine         log      = 2;
+    Progress        progress = 3;
+    PartialResult   partial  = 4;
+    ExecuteResponse final    = 5;   // last frame; closes the stream
+  }
+}
+message NodeStarted   { google.protobuf.Timestamp at = 1; }
+message Progress      { double percent = 1; string phase = 2; }
+message PartialResult { bytes snapshot_json = 1; }
+message LogLine {
+  google.protobuf.Timestamp timestamp = 1;
+  string level    = 2;            // "debug" | "info" | "warn" | "error"
+  string message  = 3;
+  map<string, string> attributes = 4;
+}
+// =============================================================================
+// NodeError — the structured-errors contract
+// =============================================================================
+//
+// Every node in every SDK populates a NodeError the same way. Seven required
+// fields (code, category, severity, node, at, message, http_status) plus
+// strongly-encouraged fields for richer debugging:
+// - description: multi-paragraph context (what was tried, why it failed)
+// - remediation: suggested next step (actionable)
+// - context_snapshot_json: bounded slice of inputs/state at error time
+// - causes: nested wrapped errors (e.g. an HTTP error wrapping a timeout)
+//
+// SDKs auto-fill `node`, `sdk`, `sdk_version`, `runtime_kind`, `at`, and
+// `stack` from environmental context — authors never set these manually.
+//
+// See `docs/error-codes.md` for the canonical code registry.
+message NodeError {
+  // === Identity ===
+  string        code        = 1;       // STABLE machine identifier (e.g. "POSTGRES_CONNECT_TIMEOUT")
+  ErrorCategory category    = 2;
+  ErrorSeverity severity    = 3;
+  // === Origin (auto-filled by SDK) ===
+  string        node          = 4;
+  string        sdk           = 5;     // "blok-python3"
+  string        sdk_version   = 6;
+  string        runtime_kind  = 7;     // "runtime.python3"
+  google.protobuf.Timestamp at = 8;
+  // === Human-readable ===
+  string        message     = 9;       // one-sentence summary
+  string        description = 10;      // multi-paragraph context
+  string        remediation = 11;      // suggested next step
+  string        doc_url     = 12;
+  // === Causality ===
+  repeated NodeError causes = 13;
+  string             stack  = 14;
+  bytes              context_snapshot_json = 15;
+  // === Compatibility / retry hints ===
+  int32  http_status     = 16;
+  bool   retryable       = 17;
+  int64  retry_after_ms  = 18;
+  // === Category-specific structured details ===
+  // Bytes-encoded JSON. Surfaces to GlobalError.json on the runner side.
+  bytes  details_json = 19;
+}
+enum ErrorCategory {
+  CATEGORY_UNSPECIFIED = 0;
+  VALIDATION    = 1;   // input/output schema mismatch
+  CONFIGURATION = 2;   // node misconfigured
+  DEPENDENCY    = 3;   // external service failed (DB, HTTP, queue)
+  TIMEOUT       = 4;
+  PERMISSION    = 5;   // auth/authz
+  RATE_LIMIT    = 6;
+  NOT_FOUND     = 7;
+  CONFLICT      = 8;
+  CANCELLED     = 9;
+  INTERNAL      = 10;  // unexpected SDK-side bug
+  PROTOCOL      = 11;  // proto/transport issue
+  DATA          = 12;  // user data malformed (not schema validation)
+}
+enum ErrorSeverity {
+  SEVERITY_UNSPECIFIED = 0;
+  INFO  = 1;   // expected, recoverable
+  WARN  = 2;   // anomalous but workflow continues
+  ERROR = 3;   // node failed; default
+  FATAL = 4;   // workflow should abort regardless of try/catch
+}
+// =============================================================================
+// Discovery
+// =============================================================================
+message ListNodesRequest {}
+message ListNodesResponse {
+  repeated NodeDescriptor nodes = 1;
+  string sdk_name      = 2;          // "blok-python3"
+  string sdk_version   = 3;
+  string proto_version = 4;          // "1.0.0"
+}
+message NodeDescriptor {
+  string name        = 1;
+  string description = 2;
+  bytes  input_schema_json  = 3;     // JSON Schema (drives OpenAPI/Studio/LLMs)
+  bytes  output_schema_json = 4;
+  repeated string tags = 5;
+}
+// =============================================================================
+// Health (wire-compatible with grpc.health.v1)
+// =============================================================================
+message HealthRequest  { string service = 1; }
+message HealthResponse {
+  enum Status { UNKNOWN = 0; SERVING = 1; NOT_SERVING = 2; }
+  Status status      = 1;
+  string sdk_version = 2;
+  repeated string registered_nodes = 3;
+}
+// =============================================================================
+// Metrics
+// =============================================================================
+message Metrics {
+  double duration_ms    = 1;
+  double cpu_ms         = 2;
+  int64  memory_bytes   = 3;
+  int64  request_bytes  = 4;
+  int64  response_bytes = 5;
+}