@blokjs/runner 0.2.1 → 0.2.2

package/dist/adapters/grpc/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/adapters/grpc/types.d.ts

@@ -0,0 +1,97 @@
+import type { RuntimeKind } from "../RuntimeAdapter";
+/**
+ * Selectable transport between the runner and an SDK runtime.
+ *
+ * - `http` — legacy `HttpRuntimeAdapter` (POST /execute over JSON+HTTP/1).
+ * - `grpc` — `GrpcRuntimeAdapter` (NodeRuntime/Execute over HTTP/2 + protobuf).
+ */
+export type Transport = "http" | "grpc";
+/**
+ * Configuration for a {@link GrpcRuntimeAdapter} instance.
+ *
+ * Fully `readonly` — adapters never mutate their config after construction.
+ */
+export interface GrpcAdapterConfig {
+    readonly kind: RuntimeKind;
+    readonly host: string;
+    readonly port: number;
+    readonly defaultDeadlineMs: number;
+    readonly maxMessageBytes: number;
+    readonly keepalive: KeepaliveConfig;
+    readonly tls?: TlsConfig;
+    /** Optional gRPC service config JSON for retries on the Health RPC. */
+    readonly serviceConfigJson?: string;
+    /**
+     * Background health-check polling interval in ms. Set to `0` to disable
+     * (useful in tests so timers don't leak). Defaults to
+     * {@link GRPC_DEFAULTS.HEALTH_INTERVAL_MS}.
+     */
+    readonly healthCheckIntervalMs?: number;
+    /**
+     * Number of consecutive Health/Check failures that opens the circuit
+     * (subsequent `execute()` / `executeStream()` calls fail fast with a
+     * `BlokError(category=DEPENDENCY)` instead of dialing). Defaults to
+     * {@link GRPC_DEFAULTS.HEALTH_FAILURE_THRESHOLD}.
+     */
+    readonly healthCheckFailureThreshold?: number;
+}
+/**
+ * Keepalive ping configuration. gRPC sends periodic HTTP/2 PING frames so
+ * idle connections don't drop and so connection failures surface within
+ * `timeoutMs` instead of after the OS TCP timeout (~minutes).
+ */
+export interface KeepaliveConfig {
+    /** Interval between keepalive pings in ms. */
+    readonly timeMs: number;
+    /** Wait for ping ack within this many ms before considering the connection dead. */
+    readonly timeoutMs: number;
+    /** Send keepalives even when no calls are in flight. */
+    readonly permitWithoutCalls: boolean;
+}
+/**
+ * TLS / mTLS configuration. When omitted, the channel is plaintext (loopback
+ * only — `BLOK_GRPC_REQUIRE_TLS=true` enforces TLS for non-loopback).
+ */
+export interface TlsConfig {
+    /** Path to a CA certificate (PEM) for verifying the server. */
+    readonly caCertPath?: string;
+    /** Path to a client certificate (PEM) for mTLS. */
+    readonly clientCertPath?: string;
+    /** Path to a client private key (PEM) for mTLS. */
+    readonly clientKeyPath?: string;
+    /** Override the SNI hostname sent during TLS handshake. */
+    readonly serverNameOverride?: string;
+    /**
+     * Skip server certificate verification. **Development only** — adapters
+     * log a warning at startup when this is true.
+     */
+    readonly insecureSkipVerify?: boolean;
+}
+/**
+ * Default values for gRPC channel options.
+ *
+ * Single source of truth — referenced from {@link loadGrpcConfigFromEnv} and
+ * the channel-options module. No magic numbers anywhere else.
+ */
+export declare const GRPC_DEFAULTS: {
+    /** Default per-call deadline (matches today's HTTP `AbortSignal.timeout(30000)`). */
+    readonly DEFAULT_DEADLINE_MS: 30000;
+    /** Default 16MB max message size (matches the PHP `RequestBodyBuffer` ceiling from FIXES.md #5). */
+    readonly MAX_MESSAGE_BYTES: number;
+    /** Default keepalive ping interval. */
+    readonly KEEPALIVE_TIME_MS: 10000;
+    /** Default keepalive ack timeout. */
+    readonly KEEPALIVE_TIMEOUT_MS: 5000;
+    /** Send keepalives even with no in-flight calls — keeps connections warm. */
+    readonly KEEPALIVE_PERMIT_WITHOUT_CALLS: true;
+    /** Health probe interval. */
+    readonly HEALTH_INTERVAL_MS: 30000;
+    /** Consecutive Health failures that trip the circuit breaker. */
+    readonly HEALTH_FAILURE_THRESHOLD: 3;
+};
+/**
+ * Default port mapping per language. We use `HTTP_PORT + 1000` for symmetry
+ * with the existing HTTP ports (9001–9007 → 10001–10007). Operators can
+ * override per language via `RUNTIME_<KIND>_GRPC_PORT`.
+ */
+export declare const DEFAULT_GRPC_PORTS: Readonly<Record<RuntimeKind, number>>;

package/dist/adapters/grpc/types.js

@@ -0,0 +1,41 @@
+/**
+ * Default values for gRPC channel options.
+ *
+ * Single source of truth — referenced from {@link loadGrpcConfigFromEnv} and
+ * the channel-options module. No magic numbers anywhere else.
+ */
+export const GRPC_DEFAULTS = {
+    /** Default per-call deadline (matches today's HTTP `AbortSignal.timeout(30000)`). */
+    DEFAULT_DEADLINE_MS: 30_000,
+    /** Default 16MB max message size (matches the PHP `RequestBodyBuffer` ceiling from FIXES.md #5). */
+    MAX_MESSAGE_BYTES: 16 * 1024 * 1024,
+    /** Default keepalive ping interval. */
+    KEEPALIVE_TIME_MS: 10_000,
+    /** Default keepalive ack timeout. */
+    KEEPALIVE_TIMEOUT_MS: 5_000,
+    /** Send keepalives even with no in-flight calls — keeps connections warm. */
+    KEEPALIVE_PERMIT_WITHOUT_CALLS: true,
+    /** Health probe interval. */
+    HEALTH_INTERVAL_MS: 30_000,
+    /** Consecutive Health failures that trip the circuit breaker. */
+    HEALTH_FAILURE_THRESHOLD: 3,
+};
+/**
+ * Default port mapping per language. We use `HTTP_PORT + 1000` for symmetry
+ * with the existing HTTP ports (9001–9007 → 10001–10007). Operators can
+ * override per language via `RUNTIME_<KIND>_GRPC_PORT`.
+ */
+export const DEFAULT_GRPC_PORTS = {
+    nodejs: 0, // in-process; no port
+    bun: 0,
+    go: 10001,
+    rust: 10002,
+    java: 10003,
+    csharp: 10004,
+    php: 10005,
+    ruby: 10006,
+    python3: 10007,
+    docker: 0,
+    wasm: 0,
+};
+//# sourceMappingURL=types.js.map

package/dist/adapters/grpc/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/adapters/grpc/types.ts"],"names":[],"mappings":"AA0EA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC5B,qFAAqF;IACrF,mBAAmB,EAAE,MAAM;IAC3B,oGAAoG;IACpG,iBAAiB,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;IACnC,uCAAuC;IACvC,iBAAiB,EAAE,MAAM;IACzB,qCAAqC;IACrC,oBAAoB,EAAE,KAAK;IAC3B,6EAA6E;IAC7E,8BAA8B,EAAE,IAAI;IACpC,6BAA6B;IAC7B,kBAAkB,EAAE,MAAM;IAC1B,iEAAiE;IACjE,wBAAwB,EAAE,CAAC;CAClB,CAAC;AAEX;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAA0C;IACxE,MAAM,EAAE,CAAC,EAAE,sBAAsB;IACjC,GAAG,EAAE,CAAC;IACN,EAAE,EAAE,KAAK;IACT,IAAI,EAAE,KAAK;IACX,IAAI,EAAE,KAAK;IACX,MAAM,EAAE,KAAK;IACb,GAAG,EAAE,KAAK;IACV,IAAI,EAAE,KAAK;IACX,OAAO,EAAE,KAAK;IACd,MAAM,EAAE,CAAC;IACT,IAAI,EAAE,CAAC;CACP,CAAC"}

package/dist/adapters/transport.d.ts

@@ -0,0 +1,108 @@
+import type { RuntimeKind } from "./RuntimeAdapter";
+import type { TlsConfig, Transport } from "./grpc/types";
+/**
+ * Resolve the transport to use for a given runtime kind from the environment.
+ *
+ * Precedence (most specific wins):
+ *   1. `RUNTIME_<KIND>_TRANSPORT` — per-kind override
+ *      e.g. `RUNTIME_PYTHON3_TRANSPORT=http` to opt one SDK out of gRPC.
+ *   2. `RUNTIME_TRANSPORT` — global override
+ *      e.g. `RUNTIME_TRANSPORT=http` to roll back the whole runner.
+ *   3. The hard-coded default — **`grpc`** as of Phase 6 (master plan §11).
+ *      Flipped from `http` to `grpc` after the cross-language parity matrix
+ *      (`bun run test:parity`, 33 tests across 6 SDKs × 5 workflows) and
+ *      the per-SDK §17 BlokError E2E suites stayed green for the full
+ *      Phase 5 observation window.
+ *
+ * Pure function — reads `process.env` once per call so tests can override.
+ *
+ * # Why the default flip is safe
+ *
+ * - HTTP transport remains available behind `RUNTIME_TRANSPORT=http` for at
+ *   least two minor versions (master plan §11 commitment).
+ * - PHP without RoadRunner (Path B from §16) sets
+ *   `RUNTIME_PHP_TRANSPORT=http` per host. The forever-supported escape
+ *   hatch is unaffected.
+ * - SDKs that fail to bind their gRPC listener fall through the
+ *   {@link GrpcHealthChecker} circuit-breaker and surface a typed
+ *   `BlokError(category=DEPENDENCY)` per §9 — no silent failure.
+ *
+ * @param kind The runtime kind (e.g. "python3").
+ * @param env Optional env source (defaults to `process.env`). Tests can
+ *            pass a stub map.
+ * @returns Either `"http"` or `"grpc"`. Invalid values fall back to the
+ *          Phase 6 default (`grpc`).
+ */
+export declare function resolveTransportForKind(kind: RuntimeKind, env?: NodeJS.ProcessEnv): Transport;
+/**
+ * Test-only — reset the per-process HTTP-transport deprecation cache so a
+ * test that flips `RUNTIME_TRANSPORT=http` can re-assert the warning fires.
+ *
+ * @internal
+ */
+export declare function _resetHttpDeprecationCache(): void;
+/**
+ * Whether log streaming is enabled for runtime nodes. When true, the runner
+ * routes runtime nodes through `GrpcRuntimeAdapter.executeStream` instead of
+ * the unary `execute`, and `LogLine` frames flow into `RunTracker.addLog`
+ * — surfacing live in Studio's `/__blok/runs/:id/stream` SSE endpoint.
+ *
+ * Streaming is a pure additive capability: when the env var is unset, the
+ * legacy unary path runs unchanged. When enabled but the adapter doesn't
+ * support streaming (e.g. HttpRuntimeAdapter), `RuntimeAdapterNode` falls
+ * back to unary so misconfiguration never blocks execution.
+ *
+ * Recognized as truthy: `1`, `true`, `yes`, `on` (case-insensitive). Anything
+ * else (including unset, empty, `0`, `false`) returns false.
+ */
+export declare function isStreamLogsEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Resolve the gRPC background health-check interval from the environment.
+ *
+ * `BLOK_GRPC_HEALTH_INTERVAL_MS` is the global override:
+ *   - any positive integer → use that interval
+ *   - `0` → disable the loop entirely (useful in tests)
+ *   - unset / non-numeric → return undefined; adapter uses
+ *     {@link GRPC_DEFAULTS.HEALTH_INTERVAL_MS}.
+ */
+export declare function resolveHealthCheckIntervalMs(env?: NodeJS.ProcessEnv): number | undefined;
+/**
+ * Resolve the consecutive-failure threshold for the gRPC circuit breaker.
+ *
+ * `BLOK_GRPC_HEALTH_FAILURE_THRESHOLD` overrides the default
+ * ({@link GRPC_DEFAULTS.HEALTH_FAILURE_THRESHOLD}). Values < 1 are ignored
+ * (the checker requires ≥ 1 failure to trip).
+ */
+export declare function resolveHealthCheckFailureThreshold(env?: NodeJS.ProcessEnv): number | undefined;
+/**
+ * Build a {@link TlsConfig} for a given runtime kind from environment
+ * variables. Returns `undefined` when nothing is configured (channel stays
+ * plaintext — appropriate for loopback dev).
+ *
+ * Per-kind env vars (taking precedence):
+ *   - `RUNTIME_<KIND>_TLS_CA`              CA cert path (PEM)
+ *   - `RUNTIME_<KIND>_TLS_CLIENT_CERT`     client cert path (PEM, mTLS)
+ *   - `RUNTIME_<KIND>_TLS_CLIENT_KEY`      client key path (PEM, mTLS)
+ *   - `RUNTIME_<KIND>_TLS_SERVER_NAME`     SNI override
+ *   - `RUNTIME_<KIND>_TLS_INSECURE_SKIP_VERIFY=true`  dev-only
+ *
+ * Global fallbacks (apply when the per-kind var is unset):
+ *   - `BLOK_GRPC_TLS_CA`, `BLOK_GRPC_TLS_CLIENT_CERT`, `BLOK_GRPC_TLS_CLIENT_KEY`,
+ *     `BLOK_GRPC_TLS_SERVER_NAME`, `BLOK_GRPC_TLS_INSECURE_SKIP_VERIFY`.
+ *
+ * If none of the relevant env vars are set, returns `undefined`.
+ */
+export declare function loadTlsConfigForKind(kind: RuntimeKind, env?: NodeJS.ProcessEnv): TlsConfig | undefined;
+/**
+ * Whether `BLOK_GRPC_REQUIRE_TLS=true` enforces TLS on non-loopback hosts.
+ * When true, building a gRPC adapter with no TLS config against a non-loopback
+ * host throws at startup. Loopback (localhost, 127.0.0.0/8, ::1) is exempted.
+ */
+export declare function isStrictTlsEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Returns true when the host is a loopback address that doesn't require
+ * TLS even under strict mode. Match is intentionally generous — covers
+ * `localhost`, the 127.x range, IPv6 loopback, and the wildcard 0.0.0.0
+ * (which dev SDKs commonly bind to).
+ */
+export declare function isLoopbackHost(host: string): boolean;