blokctl 1.2.0 → 1.4.0

package/dist/scaffold-repo/sdks/ruby/lib/blok.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "blok/version"
+
+# Types
+require_relative "blok/types/context"
+require_relative "blok/types/request"
+require_relative "blok/types/response"
+require_relative "blok/types/node_config"
+require_relative "blok/types/execution_request"
+require_relative "blok/types/execution_result"
+require_relative "blok/types/execution_metrics"
+require_relative "blok/types/health_status"
+
+# Errors
+require_relative "blok/errors/error_category"
+require_relative "blok/errors/node_error"
+require_relative "blok/errors/blok_error"
+require_relative "blok/errors/build_context_snapshot"
+
+# Logging
+require_relative "blok/logging/log_level"
+require_relative "blok/logging/log_entry"
+require_relative "blok/logging/logger"
+
+# Node
+require_relative "blok/node/node_handler"
+require_relative "blok/node/typed_node"
+require_relative "blok/node/node_registry"
+require_relative "blok/node/discovery"
+
+# Middleware
+require_relative "blok/middleware/middleware"
+require_relative "blok/middleware/logging_middleware"
+require_relative "blok/middleware/recovery_middleware"
+
+# Validation
+require_relative "blok/validation/schema_validator"
+
+# Config
+require_relative "blok/config/server_config"
+
+# Server
+require_relative "blok/server/runtime_app"
+
+# Testing
+require_relative "blok/testing/mock_context"
+require_relative "blok/testing/test_runner"
+
+module Blok
+end

package/dist/scaffold-repo/sdks/ruby/proto/blok/runtime/v1/runtime.proto

@@ -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;
+}

package/dist/scaffold-repo/sdks/ruby/test/errors/blok_error_test.rb

@@ -0,0 +1,339 @@
+# frozen_string_literal: true
+
+require_relative "../test_helper"
+require "json"
+
+# Unit tests for the structured +Blok::Errors::BlokError+ per master plan §17.
+#
+# Coverage parallels Python (+test_blok_error.py+), Go (+blok_error_test.go+),
+# Rust (+blok_error::tests+), Java (+BlokErrorTest+), and C#
+# (+BlokErrorTests+). Each SDK exhaustively tests the same API surface so
+# the cross-language wire shape stays in lockstep.
+class TestBlokError < Minitest::Test
+  C  = Blok::Errors::BlokError::Category
+  S  = Blok::Errors::BlokError::Severity
+  BE = Blok::Errors::BlokError
+
+  # ===== Category defaults =================================================
+
+  def test_category_default_status_matches_table
+    assert_equal 400, C::DEFAULT_HTTP_STATUS[C::VALIDATION]
+    assert_equal 500, C::DEFAULT_HTTP_STATUS[C::CONFIGURATION]
+    assert_equal 502, C::DEFAULT_HTTP_STATUS[C::DEPENDENCY]
+    assert_equal 504, C::DEFAULT_HTTP_STATUS[C::TIMEOUT]
+    assert_equal 403, C::DEFAULT_HTTP_STATUS[C::PERMISSION]
+    assert_equal 429, C::DEFAULT_HTTP_STATUS[C::RATE_LIMIT]
+    assert_equal 404, C::DEFAULT_HTTP_STATUS[C::NOT_FOUND]
+    assert_equal 409, C::DEFAULT_HTTP_STATUS[C::CONFLICT]
+    assert_equal 499, C::DEFAULT_HTTP_STATUS[C::CANCELLED]
+    assert_equal 500, C::DEFAULT_HTTP_STATUS[C::INTERNAL]
+    assert_equal 502, C::DEFAULT_HTTP_STATUS[C::PROTOCOL]
+    assert_equal 422, C::DEFAULT_HTTP_STATUS[C::DATA]
+  end
+
+  def test_category_default_retryable_matches_table
+    assert C::DEFAULT_RETRYABLE[C::DEPENDENCY]
+    assert C::DEFAULT_RETRYABLE[C::TIMEOUT]
+    assert C::DEFAULT_RETRYABLE[C::RATE_LIMIT]
+    refute C::DEFAULT_RETRYABLE[C::VALIDATION]
+    refute C::DEFAULT_RETRYABLE[C::INTERNAL]
+    refute C::DEFAULT_RETRYABLE[C::CONFLICT]
+  end
+
+  def test_category_parse_unknown_falls_back_to_internal
+    assert_equal C::DEPENDENCY, C.parse("DEPENDENCY")
+    assert_equal C::INTERNAL,   C.parse("not-a-thing")
+    assert_equal C::INTERNAL,   C.parse(nil)
+  end
+
+  def test_severity_parse_falls_back_to_error
+    assert_equal S::INFO,  S.parse("INFO")
+    assert_equal S::ERROR, S.parse("xyz")
+    assert_equal S::ERROR, S.parse(nil)
+  end
+
+  # ===== Builder ===========================================================
+
+  def test_builder_dependency_defaults
+    e = BE.dependency(code: "X", message: "y")
+    assert_equal C::DEPENDENCY, e.category
+    assert_equal 502, e.http_status
+    assert e.retryable
+    assert_equal S::ERROR, e.severity
+  end
+
+  def test_builder_validation_defaults
+    e = BE.validation(code: "V", message: "v")
+    assert_equal C::VALIDATION, e.category
+    assert_equal 400, e.http_status
+    refute e.retryable
+  end
+
+  def test_builder_overrides_take_priority
+    e = BE.dependency(code: "X", message: "y", http_status: 599, retryable: false, severity: S::FATAL)
+    assert_equal 599, e.http_status
+    refute e.retryable
+    assert_equal S::FATAL, e.severity
+  end
+
+  def test_builder_retry_after_ms_direct
+    e = BE.timeout(code: "T", message: "t", retry_after_ms: 750)
+    assert_equal 750, e.retry_after_ms
+  end
+
+  def test_builder_details_round_trip
+    details = { "issues" => [{ "path" => ["email"] }] }
+    e = BE.validation(code: "V", message: "m", details: details)
+    assert_equal "email", e.details["issues"][0]["path"][0]
+  end
+
+  def test_builder_cause_populates_causes_list
+    cause = StandardError.new("nope")
+    e = BE.dependency(code: "X", message: "y", cause: cause)
+    refute_empty e.causes
+    assert_equal "INTERNAL", e.causes[0]["category"]
+    assert_equal "nope", e.causes[0]["message"]
+  end
+
+  def test_all_twelve_category_factories_produce_correct_category
+    assert_equal C::VALIDATION,    BE.validation(code: "x", message: "y").category
+    assert_equal C::CONFIGURATION, BE.configuration(code: "x", message: "y").category
+    assert_equal C::DEPENDENCY,    BE.dependency(code: "x", message: "y").category
+    assert_equal C::TIMEOUT,       BE.timeout(code: "x", message: "y").category
+    assert_equal C::PERMISSION,    BE.permission(code: "x", message: "y").category
+    assert_equal C::RATE_LIMIT,    BE.rate_limit(code: "x", message: "y").category
+    assert_equal C::NOT_FOUND,     BE.not_found(code: "x", message: "y").category
+    assert_equal C::CONFLICT,      BE.conflict(code: "x", message: "y").category
+    assert_equal C::CANCELLED,     BE.cancelled(code: "x", message: "y").category
+    assert_equal C::INTERNAL,      BE.internal(code: "x", message: "y").category
+    assert_equal C::PROTOCOL,      BE.protocol(code: "x", message: "y").category
+    assert_equal C::DATA,          BE.data(code: "x", message: "y").category
+  end
+
+  # ===== from_unknown ======================================================
+
+  def test_from_unknown_passes_through_typed_blok_error
+    origin = BE::Origin.defaults(node: "auto-node", sdk_version: "1.2.3")
+    original = BE.rate_limit(code: "UPSTREAM_RATE_LIMITED", message: "limit hit")
+    recovered = BE.from_unknown(original, origin: origin)
+    assert_same original, recovered
+    assert_equal "auto-node", recovered.node
+    assert_equal "1.2.3", recovered.sdk_version
+    assert_equal C::RATE_LIMIT, recovered.category
+  end
+
+  def test_from_unknown_wraps_throwable
+    origin = BE::Origin.defaults(node: "auto", sdk_version: "1.0.0")
+    cause = ArgumentError.new("disk full")
+    wrapped = BE.from_unknown(cause, origin: origin)
+    assert_equal C::INTERNAL, wrapped.category
+    assert_equal "disk full", wrapped.message
+    assert wrapped.code.start_with?("UNCAUGHT_")
+  end
+
+  def test_from_unknown_wraps_string
+    origin = BE::Origin.defaults(node: "x", sdk_version: "1.0.0")
+    wrapped = BE.from_unknown("boom", origin: origin)
+    assert_equal C::INTERNAL, wrapped.category
+    assert_equal "boom", wrapped.message
+    assert_equal "UNCAUGHT_ERROR", wrapped.code
+    assert_equal "boom", wrapped.details["message"]
+  end
+
+  def test_from_unknown_wraps_hash
+    origin = BE::Origin.defaults(node: "x", sdk_version: "1.0.0")
+    raw = { "message" => "from-map", "custom" => 42 }
+    wrapped = BE.from_unknown(raw, origin: origin)
+    assert_equal "from-map", wrapped.message
+    assert_equal C::INTERNAL, wrapped.category
+    assert_equal 42, wrapped.details["custom"]
+  end
+
+  def test_from_unknown_handles_nil
+    origin = BE::Origin.defaults(node: "x", sdk_version: "1.0.0")
+    wrapped = BE.from_unknown(nil, origin: origin)
+    assert_equal "node error", wrapped.message
+    assert_equal C::INTERNAL, wrapped.category
+  end
+
+  def test_from_unknown_wraps_legacy_node_error
+    origin = BE::Origin.defaults(node: "x", sdk_version: "1.0.0")
+    legacy = Blok::Errors::NodeError.network("postgres unreachable")
+    wrapped = BE.from_unknown(legacy, origin: origin)
+    assert_equal C::INTERNAL, wrapped.category
+    assert_equal "UNCAUGHT_NODEERROR", wrapped.code
+    assert_includes wrapped.message, "postgres unreachable"
+    refute_nil wrapped.details
+  end
+
+  # ===== to_hash / from_hash ===============================================
+
+  def test_to_hash_and_from_hash_round_trip
+    details = { "a" => 1 }
+    e = BE.dependency(
+      code: "CODE", message: "msg", description: "desc", remediation: "rem",
+      doc_url: "https://example.com", retryable: true, retry_after_ms: 1234,
+      details: details, node: "n", sdk: "blok-ruby", sdk_version: "1.0.0",
+      runtime_kind: "runtime.ruby"
+    )
+    map = e.to_hash
+    assert_equal "DEPENDENCY", map["category"]
+    assert_equal "CODE", map["code"]
+    assert_equal 502, map["http_status"]
+    assert_equal 1234, map["retry_after_ms"]
+
+    restored = BE.from_hash(map)
+    assert_equal C::DEPENDENCY, restored.category
+    assert_equal "CODE", restored.code
+    assert_equal "msg", restored.message
+    assert_equal "desc", restored.description
+    assert_equal 1234, restored.retry_after_ms
+    assert_equal "https://example.com", restored.doc_url
+  end
+
+  def test_from_hash_accepts_camel_case_keys
+    raw = {
+      "category"     => "RATE_LIMIT",
+      "severity"     => "ERROR",
+      "code"         => "RL",
+      "message"      => "too many",
+      "httpStatus"   => 429,
+      "retryable"    => true,
+      "retryAfterMs" => 60_000,
+      "at"           => "2026-04-29T00:00:00Z",
+      "sdkVersion"   => "1.0.0",
+      "runtimeKind"  => "runtime.ruby",
+      "docUrl"       => "https://docs/example"
+    }
+    e = BE.from_hash(raw)
+    assert_equal C::RATE_LIMIT, e.category
+    assert_equal 429, e.http_status
+    assert_equal 60_000, e.retry_after_ms
+    assert_equal "1.0.0", e.sdk_version
+    assert_equal "runtime.ruby", e.runtime_kind
+    assert_equal "https://docs/example", e.doc_url
+  end
+
+  def test_from_hash_accepts_causes_list
+    raw = {
+      "category" => "DEPENDENCY",
+      "severity" => "ERROR",
+      "code"     => "X",
+      "message"  => "y",
+      "causes"   => [
+        { "message" => "inner", "category" => "INTERNAL" }
+      ]
+    }
+    e = BE.from_hash(raw)
+    assert_equal 1, e.causes.length
+    assert_equal "inner", e.causes[0]["message"]
+  end
+
+  # ===== Display / Exception semantics =====================================
+
+  def test_to_string_formats_category_and_message
+    e = BE.dependency(code: "X", message: "nope")
+    assert_equal "[DEPENDENCY] nope", e.to_s
+  end
+
+  def test_can_be_raised_as_standard_error
+    e = BE.timeout(code: "X", message: "y")
+    assert_raises(BE) { raise e }
+  end
+
+  # ===== uncaught code derivation ==========================================
+
+  def test_uncaught_code_strips_namespace_and_uppercases
+    assert_equal "UNCAUGHT_IOERROR", BE._uncaught_code(IOError)
+    assert_equal "UNCAUGHT_BLOKERROR", BE._uncaught_code(BE)
+    assert_equal "UNCAUGHT_ERROR", BE._uncaught_code(nil)
+  end
+
+  # ===== cause-chain flattening ============================================
+
+  def test_flatten_causes_walks_cause_chain
+    inner = nil
+    wrap = nil
+    begin
+      begin
+        raise IOError, "inner"
+      rescue IOError
+        raise StandardError, "wrapped"
+      end
+    rescue StandardError => e
+      wrap = e
+    end
+    causes = BE.flatten_causes(wrap)
+    assert_equal 2, causes.length
+    assert_equal "wrapped", causes[0]["message"]
+    assert_equal "inner",   causes[1]["message"]
+  end
+
+  def test_flatten_causes_lifts_blok_error_link
+    inner = BE.not_found(code: "INNER", message: "inner-msg")
+    causes = BE.flatten_causes(inner)
+    assert_equal "INNER",     causes[0]["code"]
+    assert_equal "NOT_FOUND", causes[0]["category"]
+  end
+
+  # ===== BuildContextSnapshot ==============================================
+
+  def test_snapshot_preserves_small_payload
+    inputs = { "a" => 1 }
+    vars = { "k1" => "v1" }
+    snap = Blok::Errors::BuildContextSnapshot.of(inputs: inputs, vars: vars)
+    assert_equal 1,    snap["inputs"]["a"]
+    assert_equal "v1", snap["vars"]["k1"]
+  end
+
+  def test_snapshot_caps_at_max_bytes
+    inputs = {}
+    vars = {}
+    filler = "x" * 100
+    80.times { |i| vars[format("k%03d", i)] = filler }
+    snap = Blok::Errors::BuildContextSnapshot.of(inputs: inputs, vars: vars)
+    bytes = JSON.generate(snap).bytesize
+    assert bytes <= BE::CONTEXT_SNAPSHOT_MAX_BYTES + 64,
+           "snapshot #{bytes} bytes exceeded budget #{BE::CONTEXT_SNAPSHOT_MAX_BYTES}"
+  end
+
+  def test_snapshot_keeps_last_n_keys
+    inputs = {}
+    vars = {}
+    32.times { |i| vars[format("k%02d", i)] = i }
+    snap = Blok::Errors::BuildContextSnapshot.with_opts(
+      inputs: inputs, vars: vars, max_bytes: 0, max_vars_keys: 5
+    )
+    kept = snap["vars"]
+    assert_equal 5, kept.length
+    assert kept.key?("k31")
+    refute kept.key?("k00")
+  end
+
+  def test_snapshot_disables_var_keys_when_zero
+    inputs = {}
+    vars = { "only" => 1 }
+    snap = Blok::Errors::BuildContextSnapshot.with_opts(
+      inputs: inputs, vars: vars, max_bytes: 0, max_vars_keys: 0
+    )
+    assert_empty snap["vars"]
+  end
+
+  # ===== Origin ============================================================
+
+  def test_origin_defaults_uses_sdk_constants
+    o = BE::Origin.defaults(node: "n", sdk_version: "1.2.3")
+    assert_equal BE::DEFAULT_SDK_NAME,     o.sdk
+    assert_equal BE::DEFAULT_RUNTIME_KIND, o.runtime_kind
+    assert_equal "n",     o.node
+    assert_equal "1.2.3", o.sdk_version
+  end
+
+  def test_apply_origin_if_missing_preserves_explicit_fields
+    e = BE.internal(code: "X", message: "y", node: "explicit")
+    e.apply_origin_if_missing(BE::Origin.defaults(node: "auto", sdk_version: "1.0.0"))
+    assert_equal "explicit",                e.node
+    assert_equal BE::DEFAULT_SDK_NAME,      e.sdk
+    assert_equal BE::DEFAULT_RUNTIME_KIND,  e.runtime_kind
+  end
+end