@blokjs/runner 0.2.1 → 0.2.2

package/dist/adapters/grpc/GrpcErrors.js

@@ -0,0 +1,190 @@
+import { BlokError, ErrorCategory } from "@blokjs/shared";
+import { status as GrpcStatus } from "@grpc/grpc-js";
+/**
+ * Mapping table from `@grpc/grpc-js` `status` codes to canonical
+ * `(ErrorCategory, defaultHttpStatus)` pairs.
+ *
+ * Single source of truth for gRPC-side error classification. Adapters never
+ * branch on status codes inline; they call {@link toBlokError} which uses
+ * this table.
+ *
+ * The table is exhaustive — every gRPC status defined in
+ * `@grpc/grpc-js#status` has an entry. CI verifies coverage in the unit test.
+ */
+export const GRPC_STATUS_MAP = {
+    [GrpcStatus.OK]: { category: ErrorCategory.INTERNAL, httpStatus: 200, codePrefix: "GRPC_OK" },
+    [GrpcStatus.CANCELLED]: { category: ErrorCategory.CANCELLED, httpStatus: 499, codePrefix: "GRPC_CANCELLED" },
+    [GrpcStatus.UNKNOWN]: { category: ErrorCategory.INTERNAL, httpStatus: 500, codePrefix: "GRPC_UNKNOWN" },
+    [GrpcStatus.INVALID_ARGUMENT]: {
+        category: ErrorCategory.VALIDATION,
+        httpStatus: 400,
+        codePrefix: "GRPC_INVALID_ARGUMENT",
+    },
+    [GrpcStatus.DEADLINE_EXCEEDED]: {
+        category: ErrorCategory.TIMEOUT,
+        httpStatus: 504,
+        codePrefix: "GRPC_DEADLINE_EXCEEDED",
+    },
+    [GrpcStatus.NOT_FOUND]: { category: ErrorCategory.NOT_FOUND, httpStatus: 404, codePrefix: "GRPC_NOT_FOUND" },
+    [GrpcStatus.ALREADY_EXISTS]: { category: ErrorCategory.CONFLICT, httpStatus: 409, codePrefix: "GRPC_ALREADY_EXISTS" },
+    [GrpcStatus.PERMISSION_DENIED]: {
+        category: ErrorCategory.PERMISSION,
+        httpStatus: 403,
+        codePrefix: "GRPC_PERMISSION_DENIED",
+    },
+    [GrpcStatus.RESOURCE_EXHAUSTED]: {
+        category: ErrorCategory.RATE_LIMIT,
+        httpStatus: 429,
+        codePrefix: "GRPC_RESOURCE_EXHAUSTED",
+    },
+    [GrpcStatus.FAILED_PRECONDITION]: {
+        category: ErrorCategory.CONFIGURATION,
+        httpStatus: 412,
+        codePrefix: "GRPC_FAILED_PRECONDITION",
+    },
+    [GrpcStatus.ABORTED]: { category: ErrorCategory.CONFLICT, httpStatus: 409, codePrefix: "GRPC_ABORTED" },
+    [GrpcStatus.OUT_OF_RANGE]: { category: ErrorCategory.VALIDATION, httpStatus: 400, codePrefix: "GRPC_OUT_OF_RANGE" },
+    [GrpcStatus.UNIMPLEMENTED]: { category: ErrorCategory.PROTOCOL, httpStatus: 501, codePrefix: "GRPC_UNIMPLEMENTED" },
+    [GrpcStatus.INTERNAL]: { category: ErrorCategory.INTERNAL, httpStatus: 500, codePrefix: "GRPC_INTERNAL" },
+    [GrpcStatus.UNAVAILABLE]: { category: ErrorCategory.DEPENDENCY, httpStatus: 503, codePrefix: "GRPC_UNAVAILABLE" },
+    [GrpcStatus.DATA_LOSS]: { category: ErrorCategory.PROTOCOL, httpStatus: 500, codePrefix: "GRPC_DATA_LOSS" },
+    [GrpcStatus.UNAUTHENTICATED]: {
+        category: ErrorCategory.PERMISSION,
+        httpStatus: 401,
+        codePrefix: "GRPC_UNAUTHENTICATED",
+    },
+};
+/**
+ * Convert a gRPC `ServiceError` (or any thrown value from a gRPC call) into a
+ * canonical {@link BlokError}. Lossless when the SDK populates structured
+ * details: gRPC `status.details` carrying a serialized {@link NodeErrorPayload}
+ * is decoded and merged into the resulting error.
+ *
+ * Behavior:
+ * - `ServiceError` with a known `code`: looked up in {@link GRPC_STATUS_MAP}.
+ *   If `metadata` carries `blok-error-bin` (a serialized NodeErrorPayload),
+ *   the payload is reconstructed via {@link BlokError.fromJSON} and the
+ *   gRPC status only refines the http_status / category fallback.
+ * - Plain `Error`: wrapped via {@link BlokError.fromUnknown}.
+ * - Anything else: stringified and wrapped as `INTERNAL`.
+ */
+export function toBlokError(err, ctx) {
+    if (err instanceof BlokError)
+        return err;
+    if (isServiceError(err)) {
+        const payload = tryReadStructuredPayload(err);
+        if (payload) {
+            // SDK supplied a structured NodeError — round-trip it back into a
+            // BlokError so all 19 fields survive intact.
+            const rehydrated = BlokError.fromJSON(payload);
+            // The gRPC status is the more authoritative source for code/category
+            // fallback only when the payload didn't supply them. Since fromJSON
+            // already restored category, we leave it alone.
+            return rehydrated;
+        }
+        const mapping = GRPC_STATUS_MAP[err.code] ?? GRPC_STATUS_MAP[GrpcStatus.UNKNOWN];
+        return BlokError[categoryFactoryName(mapping.category)]({
+            code: mapping.codePrefix,
+            message: err.details || err.message || `gRPC ${GrpcStatus[err.code]} from ${ctx.runtimeKind}`,
+            httpStatus: mapping.httpStatus,
+            node: ctx.node,
+            sdk: ctx.sdk,
+            sdkVersion: ctx.sdkVersion,
+            runtimeKind: ctx.runtimeKind,
+            details: { grpcStatus: GrpcStatus[err.code], grpcMessage: err.message },
+        });
+    }
+    return BlokError.fromUnknown(err, ctx);
+}
+/**
+ * Type guard for {@link ServiceError}. Duck-typed because `instanceof` checks
+ * across `@grpc/grpc-js` module boundaries are unreliable when the dep is
+ * deduped at multiple versions.
+ */
+export function isServiceError(err) {
+    return (!!err &&
+        typeof err === "object" &&
+        "code" in err &&
+        typeof err.code === "number" &&
+        "details" in err);
+}
+/**
+ * Read the `blok-error-bin` metadata key (if set) and parse it as a
+ * {@link NodeErrorPayload}. Returns `null` if the key is absent or invalid.
+ *
+ * This is how SDKs propagate the full structured error: they put the
+ * serialized payload into `Metadata.set("blok-error-bin", buffer)` and the
+ * runner reads it here.
+ */
+function tryReadStructuredPayload(err) {
+    const metadata = err.metadata;
+    if (!metadata)
+        return null;
+    const values = metadata.get("blok-error-bin");
+    if (!values || values.length === 0)
+        return null;
+    const first = values[0];
+    if (!(first instanceof Buffer))
+        return null;
+    try {
+        const parsed = JSON.parse(first.toString("utf-8"));
+        if (parsed && typeof parsed === "object" && "code" in parsed && "category" in parsed) {
+            return parsed;
+        }
+    }
+    catch {
+        /* malformed metadata — fall through to status-based mapping */
+    }
+    return null;
+}
+/**
+ * Translate a `BlokError` produced by the runner side back into a gRPC status
+ * code, for cases where the runner needs to report failure to a downstream
+ * caller using gRPC. Inverse of {@link GRPC_STATUS_MAP}.
+ *
+ * Currently used only by tests; will be used by Phase 5 streaming when the
+ * runner re-emits node errors as `ExecuteStream` `final` frames.
+ */
+export function categoryToGrpcStatus(category) {
+    for (const [statusKey, mapping] of Object.entries(GRPC_STATUS_MAP)) {
+        if (mapping.category === category) {
+            return Number(statusKey);
+        }
+    }
+    return GrpcStatus.INTERNAL;
+}
+/**
+ * Map an {@link ErrorCategory} to its corresponding {@link BlokError} factory
+ * method name. Single-source-of-truth for category → factory dispatch.
+ */
+function categoryFactoryName(category) {
+    switch (category) {
+        case ErrorCategory.VALIDATION:
+            return "validation";
+        case ErrorCategory.CONFIGURATION:
+            return "configuration";
+        case ErrorCategory.DEPENDENCY:
+            return "dependency";
+        case ErrorCategory.TIMEOUT:
+            return "timeout";
+        case ErrorCategory.PERMISSION:
+            return "permission";
+        case ErrorCategory.RATE_LIMIT:
+            return "rateLimit";
+        case ErrorCategory.NOT_FOUND:
+            return "notFound";
+        case ErrorCategory.CONFLICT:
+            return "conflict";
+        case ErrorCategory.CANCELLED:
+            return "cancelled";
+        case ErrorCategory.INTERNAL:
+            return "internal";
+        case ErrorCategory.PROTOCOL:
+            return "protocol";
+        case ErrorCategory.DATA:
+            return "data";
+        default:
+            return "internal";
+    }
+}
+//# sourceMappingURL=GrpcErrors.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GrpcErrors.js","sourceRoot":"","sources":["../../../src/adapters/grpc/GrpcErrors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAyB,MAAM,gBAAgB,CAAC;AACjF,OAAO,EAAE,MAAM,IAAI,UAAU,EAAqB,MAAM,eAAe,CAAC;AAExE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,eAAe,GAExB;IACH,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,QAAQ,EAAE,aAAa,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE;IAC7F,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,EAAE,QAAQ,EAAE,aAAa,CAAC,SAAS,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,gBAAgB,EAAE;IAC5G,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,EAAE,QAAQ,EAAE,aAAa,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,cAAc,EAAE;IACvG,CAAC,UAAU,CAAC,gBAAgB,CAAC,EAAE;QAC9B,QAAQ,EAAE,aAAa,CAAC,UAAU;QAClC,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,uBAAuB;KACnC;IACD,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE;QAC/B,QAAQ,EAAE,aAAa,CAAC,OAAO;QAC/B,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,wBAAwB;KACpC;IACD,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,EAAE,QAAQ,EAAE,aAAa,CAAC,SAAS,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,gBAAgB,EAAE;IAC5G,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,EAAE,QAAQ,EAAE,aAAa,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,qBAAqB,EAAE;IACrH,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE;QAC/B,QAAQ,EAAE,aAAa,CAAC,UAAU;QAClC,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,wBAAwB;KACpC;IACD,CAAC,UAAU,CAAC,kBAAkB,CAAC,EAAE;QAChC,QAAQ,EAAE,aAAa,CAAC,UAAU;QAClC,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,yBAAyB;KACrC;IACD,CAAC,UAAU,CAAC,mBAAmB,CAAC,EAAE;QACjC,QAAQ,EAAE,aAAa,CAAC,aAAa;QACrC,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,0BAA0B;KACtC;IACD,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,EAAE,QAAQ,EAAE,aAAa,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,cAAc,EAAE;IACvG,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,EAAE,QAAQ,EAAE,aAAa,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,mBAAmB,EAAE;IACnH,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,EAAE,QAAQ,EAAE,aAAa,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,oBAAoB,EAAE;IACnH,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,EAAE,aAAa,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,eAAe,EAAE;IACzG,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,EAAE,QAAQ,EAAE,aAAa,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,kBAAkB,EAAE;IACjH,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,EAAE,QAAQ,EAAE,aAAa,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,gBAAgB,EAAE;IAC3G,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE;QAC7B,QAAQ,EAAE,aAAa,CAAC,UAAU;QAClC,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,sBAAsB;KAClC;CACD,CAAC;AAcF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAAC,GAAY,EAAE,GAAqB;IAC9D,IAAI,GAAG,YAAY,SAAS;QAAE,OAAO,GAAG,CAAC;IAEzC,IAAI,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,wBAAwB,CAAC,GAAG,CAAC,CAAC;QAC9C,IAAI,OAAO,EAAE,CAAC;YACb,kEAAkE;YAClE,6CAA6C;YAC7C,MAAM,UAAU,GAAG,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YAC/C,qEAAqE;YACrE,oEAAoE;YACpE,gDAAgD;YAChD,OAAO,UAAU,CAAC;QACnB,CAAC;QAED,MAAM,OAAO,GAAG,eAAe,CAAC,GAAG,CAAC,IAAkB,CAAC,IAAI,eAAe,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QAC/F,OAAO,SAAS,CAAC,mBAAmB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;YACvD,IAAI,EAAE,OAAO,CAAC,UAAU;YACxB,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,OAAO,IAAI,QAAQ,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,WAAW,EAAE;YAC7F,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,GAAG,EAAE,GAAG,CAAC,GAAG;YACZ,UAAU,EAAE,GAAG,CAAC,UAAU;YAC1B,WAAW,EAAE,GAAG,CAAC,WAAW;YAC5B,OAAO,EAAE,EAAE,UAAU,EAAE,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,OAAO,EAAE;SACvE,CAAC,CAAC;IACJ,CAAC;IAED,OAAO,SAAS,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AACxC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY;IAC1C,OAAO,CACN,CAAC,CAAC,GAAG;QACL,OAAO,GAAG,KAAK,QAAQ;QACvB,MAAM,IAAI,GAAG;QACb,OAAQ,GAAyB,CAAC,IAAI,KAAK,QAAQ;QACnD,SAAS,IAAI,GAAG,CAChB,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,wBAAwB,CAAC,GAAiB;IAClD,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC;IAC9B,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3B,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAC9C,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAChD,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACxB,IAAI,CAAC,CAAC,KAAK,YAAY,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAE5C,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;QACnD,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,IAAI,MAAM,IAAI,UAAU,IAAI,MAAM,EAAE,CAAC;YACtF,OAAO,MAA0B,CAAC;QACnC,CAAC;IACF,CAAC;IAAC,MAAM,CAAC;QACR,+DAA+D;IAChE,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAuB;IAC3D,KAAK,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,CAAC;QACpE,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACnC,OAAO,MAAM,CAAC,SAAS,CAAe,CAAC;QACxC,CAAC;IACF,CAAC;IACD,OAAO,UAAU,CAAC,QAAQ,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,SAAS,mBAAmB,CAAC,QAAuB;IACnD,QAAQ,QAAQ,EAAE,CAAC;QAClB,KAAK,aAAa,CAAC,UAAU;YAC5B,OAAO,YAAY,CAAC;QACrB,KAAK,aAAa,CAAC,aAAa;YAC/B,OAAO,eAAe,CAAC;QACxB,KAAK,aAAa,CAAC,UAAU;YAC5B,OAAO,YAAY,CAAC;QACrB,KAAK,aAAa,CAAC,OAAO;YACzB,OAAO,SAAS,CAAC;QAClB,KAAK,aAAa,CAAC,UAAU;YAC5B,OAAO,YAAY,CAAC;QACrB,KAAK,aAAa,CAAC,UAAU;YAC5B,OAAO,WAAW,CAAC;QACpB,KAAK,aAAa,CAAC,SAAS;YAC3B,OAAO,UAAU,CAAC;QACnB,KAAK,aAAa,CAAC,QAAQ;YAC1B,OAAO,UAAU,CAAC;QACnB,KAAK,aAAa,CAAC,SAAS;YAC3B,OAAO,WAAW,CAAC;QACpB,KAAK,aAAa,CAAC,QAAQ;YAC1B,OAAO,UAAU,CAAC;QACnB,KAAK,aAAa,CAAC,QAAQ;YAC1B,OAAO,UAAU,CAAC;QACnB,KAAK,aAAa,CAAC,IAAI;YACtB,OAAO,MAAM,CAAC;QACf;YACC,OAAO,UAAU,CAAC;IACpB,CAAC;AACF,CAAC"}

package/dist/adapters/grpc/GrpcHealthChecker.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Background health probe + circuit breaker for a single gRPC adapter.
+ *
+ * Per the master plan §9: each {@link GrpcRuntimeAdapter} polls
+ * `Health/Check` on a fixed interval; after `failureThreshold` consecutive
+ * failures, the circuit opens and `execute()` / `executeStream()` fail fast
+ * with a typed `BlokError(category=DEPENDENCY)` instead of dialing the SDK.
+ * The first successful probe closes the circuit again.
+ *
+ * Design notes
+ * - Pure logic + a `setInterval` timer — no transport coupling. The
+ *   `probe` callback abstracts over `adapter.checkHealth()` so this class
+ *   can be unit-tested without spawning a real gRPC server.
+ * - State transitions go through `setAvailable()` so the (optional)
+ *   `onStateChange` hook fires exactly once per transition. Useful for
+ *   structured logging + future observability counters.
+ * - Stops cleanly via {@link stop} which is idempotent and unrefs the
+ *   timer so it never blocks process shutdown in tests.
+ *
+ * Single Responsibility: track availability based on Health probes; expose
+ * `isAvailable()` for callers to gate work. Nothing else.
+ */
+export interface HealthCheckerOptions {
+    /** Polling interval in ms. Must be > 0. */
+    readonly intervalMs: number;
+    /** Consecutive failures that open the circuit. Must be ≥ 1. */
+    readonly failureThreshold: number;
+    /** Optional hook fired exactly once per `available` state transition. */
+    readonly onStateChange?: (available: boolean) => void;
+}
+/**
+ * The probe function the checker calls on each tick. Returns `true` when
+ * the adapter is reachable + reports SERVING; `false` for any other
+ * outcome (network error, NOT_SERVING, deadline). The checker NEVER
+ * receives an exception — adapters MUST resolve `false` on failure so
+ * the polling loop is stable.
+ */
+export type HealthProbe = () => Promise<boolean>;
+export declare class GrpcHealthChecker {
+    private readonly probe;
+    private readonly options;
+    private timer;
+    private inflight;
+    private failures;
+    private available;
+    private started;
+    constructor(probe: HealthProbe, options: HealthCheckerOptions);
+    /**
+     * Begin polling. Idempotent — calling `start()` twice is a no-op. Does
+     * NOT run an immediate probe; the first tick fires after `intervalMs`.
+     */
+    start(): void;
+    /** Stop polling. Idempotent. Resets internal state for a future restart. */
+    stop(): void;
+    /**
+     * True when the circuit is closed (calls allowed). False after enough
+     * consecutive failures to trip the breaker.
+     */
+    isAvailable(): boolean;
+    /** Current consecutive-failure count. Useful for diagnostics + tests. */
+    getFailureCount(): number;
+    /**
+     * Run a single probe round. Exposed so tests can drive the state
+     * machine deterministically without waiting for the interval timer.
+     * Concurrent ticks are coalesced (a slow probe doesn't queue more).
+     */
+    tick(): Promise<void>;
+    private setAvailable;
+}

package/dist/adapters/grpc/GrpcHealthChecker.js

@@ -0,0 +1,96 @@
+export class GrpcHealthChecker {
+    probe;
+    options;
+    timer = null;
+    inflight = false;
+    failures = 0;
+    available = true;
+    started = false;
+    constructor(probe, options) {
+        this.probe = probe;
+        this.options = options;
+        if (options.intervalMs <= 0) {
+            throw new Error("GrpcHealthChecker: intervalMs must be > 0 (use start/stop to toggle polling)");
+        }
+        if (options.failureThreshold < 1) {
+            throw new Error("GrpcHealthChecker: failureThreshold must be ≥ 1");
+        }
+    }
+    /**
+     * Begin polling. Idempotent — calling `start()` twice is a no-op. Does
+     * NOT run an immediate probe; the first tick fires after `intervalMs`.
+     */
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        this.timer = setInterval(() => {
+            void this.tick();
+        }, this.options.intervalMs);
+        // Don't keep the event loop alive just for this timer — important
+        // for tests that don't explicitly call `stop()`.
+        if (typeof this.timer.unref === "function")
+            this.timer.unref();
+    }
+    /** Stop polling. Idempotent. Resets internal state for a future restart. */
+    stop() {
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        this.started = false;
+    }
+    /**
+     * True when the circuit is closed (calls allowed). False after enough
+     * consecutive failures to trip the breaker.
+     */
+    isAvailable() {
+        return this.available;
+    }
+    /** Current consecutive-failure count. Useful for diagnostics + tests. */
+    getFailureCount() {
+        return this.failures;
+    }
+    /**
+     * Run a single probe round. Exposed so tests can drive the state
+     * machine deterministically without waiting for the interval timer.
+     * Concurrent ticks are coalesced (a slow probe doesn't queue more).
+     */
+    async tick() {
+        if (this.inflight)
+            return;
+        this.inflight = true;
+        try {
+            const healthy = await this.probe();
+            if (healthy) {
+                this.failures = 0;
+                this.setAvailable(true);
+            }
+            else {
+                this.failures += 1;
+                if (this.failures >= this.options.failureThreshold) {
+                    this.setAvailable(false);
+                }
+            }
+        }
+        catch {
+            // Defensive: probe failures must already resolve `false`. If a
+            // probe throws anyway, treat it as a failure and never let the
+            // exception escape (would crash the timer callback).
+            this.failures += 1;
+            if (this.failures >= this.options.failureThreshold) {
+                this.setAvailable(false);
+            }
+        }
+        finally {
+            this.inflight = false;
+        }
+    }
+    setAvailable(next) {
+        if (next === this.available)
+            return;
+        this.available = next;
+        this.options.onStateChange?.(next);
+    }
+}
+//# sourceMappingURL=GrpcHealthChecker.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GrpcHealthChecker.js","sourceRoot":"","sources":["../../../src/adapters/grpc/GrpcHealthChecker.ts"],"names":[],"mappings":"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"}

package/dist/adapters/grpc/GrpcRuntimeAdapter.d.ts

@@ -0,0 +1,98 @@
+import { type Context } from "@blokjs/shared";
+import type RunnerNode from "../../RunnerNode";
+import type { ExecutionResult, RuntimeAdapter, RuntimeKind } from "../RuntimeAdapter";
+import { GrpcClientPool } from "./GrpcClientPool";
+import { type DecodedExecuteEvent } from "./GrpcCodec";
+import { type GrpcAdapterConfig } from "./types";
+/**
+ * Runtime adapter that executes a node by calling
+ * `blok.runtime.v1.NodeRuntime/Execute` over gRPC.
+ *
+ * Sibling to {@link HttpRuntimeAdapter}. Implements the same
+ * {@link RuntimeAdapter} interface, so {@link Configuration} can swap between
+ * transports based on env without any caller change.
+ *
+ * Single Responsibility: orchestrate the unary `Execute` RPC.
+ *
+ * Encoding/decoding is delegated to {@link GrpcCodec}; error mapping to
+ * {@link GrpcErrors}; client lifetime to {@link GrpcClientPool}; channel
+ * options to {@link GrpcChannelOptions}.
+ *
+ * @example
+ *   const adapter = new GrpcRuntimeAdapter({
+ *     kind: "python3",
+ *     host: "localhost",
+ *     port: 10007,
+ *     defaultDeadlineMs: 30_000,
+ *     maxMessageBytes: 16 * 1024 * 1024,
+ *     keepalive: { timeMs: 10000, timeoutMs: 5000, permitWithoutCalls: true },
+ *   });
+ *   const result = await adapter.execute(node, ctx);
+ */
+export declare class GrpcRuntimeAdapter implements RuntimeAdapter {
+    readonly kind: RuntimeKind;
+    readonly transport: "grpc";
+    private readonly config;
+    private readonly pool;
+    private readonly ownsPool;
+    private readonly healthChecker;
+    private readonly tracer;
+    constructor(config: GrpcAdapterConfig, pool?: GrpcClientPool);
+    /**
+     * Lazily start the background health-check loop. Operators can disable
+     * the loop with `healthCheckIntervalMs: 0`. Tests typically construct
+     * adapters without starting the loop and use {@link checkHealth}
+     * directly.
+     */
+    startHealthCheck(): void;
+    private buildHealthChecker;
+    /** Build a typed `BlokError(category=DEPENDENCY)` for short-circuited calls. */
+    private circuitOpenError;
+    execute(node: RunnerNode, ctx: Context): Promise<ExecutionResult>;
+    /**
+     * Open a server-streaming `ExecuteStream` call and return both an
+     * AsyncIterable of decoded events AND a promise that resolves to the
+     * final {@link ExecutionResult} once the stream completes.
+     *
+     * Phase 5 capability: SDKs may emit `NodeStarted`, `LogLine`, `Progress`,
+     * and `PartialResult` events while a node executes; the stream always
+     * terminates with a single `final` event carrying the same
+     * {@link ExecuteResponseProto} that unary `Execute` would return.
+     *
+     * SDKs that don't implement streaming respond with gRPC `UNIMPLEMENTED`;
+     * the returned promise rejects with a {@link BlokError} of category
+     * `INTERNAL` (mapped from `UNIMPLEMENTED`) and the iterable yields nothing.
+     *
+     * Callers should consume the iterable in parallel with awaiting the
+     * promise — events are pushed live, while the promise gives the typed
+     * result for the rest of the runner pipeline.
+     *
+     * @example
+     *   const { events, result } = adapter.executeStream(node, ctx);
+     *   for await (const ev of events) {
+     *     if (ev.type === "log") tracker.appendLog(ev.log);
+     *   }
+     *   const final = await result;
+     */
+    executeStream(node: RunnerNode, ctx: Context): {
+        events: AsyncIterable<DecodedExecuteEvent>;
+        result: Promise<ExecutionResult>;
+    };
+    private openExecuteStream;
+    /**
+     * Probe the SDK with `Health/Check`. Used by the health-check loop in
+     * `TriggerBase` and by the circuit breaker. Returns false on any failure
+     * (network, deadline, NOT_SERVING) — never throws.
+     */
+    checkHealth(): Promise<boolean>;
+    /**
+     * Close the underlying client pool and stop the health-check loop.
+     * Pool close is only effective when the pool is owned by this adapter.
+     */
+    close(): void;
+    private unaryExecute;
+    private unaryHealth;
+    private toExecutionResult;
+    private decodedErrorToBlokError;
+    private errorContext;
+}