@service-bridge/node 0.1.3

package/sdk/src/grpc-client.ts

@@ -0,0 +1,2924 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import * as crypto from "node:crypto";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as grpc from "@grpc/grpc-js";
+import * as protoLoader from "@grpc/proto-loader";
+import * as protobufjs from "protobufjs/light";
+
+export interface TraceCtx {
+  traceId: string;
+  spanId: string;
+}
+
+const traceStorage = new AsyncLocalStorage<TraceCtx>();
+
+export function getTraceContext(): TraceCtx | undefined {
+  return traceStorage.getStore();
+}
+
+export function runWithTraceContext<T>(ctx: TraceCtx, fn: () => T): T {
+  return traceStorage.run(ctx, fn);
+}
+
+type DeadlineOptions = { deadline: Date; waitForReady?: boolean };
+
+type RegistryFunctionWire = {
+  endpoints?: unknown;
+  input_schema_json?: string;
+  output_schema_json?: string;
+  allowed_callers?: unknown;
+};
+
+type WorkerHandleRequest = {
+  fn: string;
+  payload?: Buffer;
+  trace_id?: string;
+  span_id?: string;
+};
+
+type WorkerHandleResponse = {
+  output?: Buffer;
+  success: boolean;
+  error?: string;
+};
+
+type WorkerDeliverRequest = {
+  group_name?: string;
+  payload?: Buffer;
+  trace_id?: string;
+  parent_span_id?: string;
+  topic?: string;
+  message_id?: string;
+  attempt?: unknown;
+  headers?: Record<string, unknown>;
+};
+
+type WorkerDeliverResponse = {
+  ack: boolean;
+  error?: string;
+  reject_reason?: string;
+  retry_after_ms?: number;
+};
+
+type RunChunkWire = {
+  type?: string;
+  key?: string;
+  sequence?: unknown;
+  data?: Buffer | Uint8Array | string;
+  run_status?: string;
+};
+
+type RunWatchStream = grpc.ClientReadableStream<RunChunkWire>;
+
+interface WorkerClient {
+  Handle(
+    req: WorkerHandleRequest,
+    md: grpc.Metadata,
+    opts: DeadlineOptions,
+    cb: (err: Error | null, res?: WorkerHandleResponse) => void,
+  ): void;
+  close?(): void;
+}
+
+interface ControlPlaneClient {
+  LookupFunction(
+    req: { fn_name: string },
+    md: grpc.Metadata,
+    opts: DeadlineOptions,
+    cb: (
+      err: Error | null,
+      res?: {
+        found?: boolean;
+        canonical_name?: string;
+        endpoints?: RegistryFunctionWire;
+      },
+    ) => void,
+  ): void;
+  Publish(
+    req: unknown,
+    md: grpc.Metadata,
+    opts: DeadlineOptions,
+    cb: (err: Error | null, res?: { message_id?: string }) => void,
+  ): void;
+  RegisterJob(
+    req: unknown,
+    md: grpc.Metadata,
+    opts: DeadlineOptions,
+    cb: (err: Error | null, res?: { id?: string }) => void,
+  ): void;
+  RegisterWorkflow(
+    req: unknown,
+    md: grpc.Metadata,
+    opts: DeadlineOptions,
+    cb: (err: Error | null, res?: { id?: string }) => void,
+  ): void;
+  ReportCallStart(
+    req: unknown,
+    md: grpc.Metadata,
+    opts: DeadlineOptions,
+    cb: (err: Error | null) => void,
+  ): void;
+  ReportCall(
+    req: unknown,
+    md: grpc.Metadata,
+    opts: DeadlineOptions,
+    cb: (err: Error | null) => void,
+  ): void;
+  ReportLog(
+    req: unknown,
+    md: grpc.Metadata,
+    opts: DeadlineOptions,
+    cb: (err: Error | null) => void,
+  ): void;
+  Heartbeat(
+    req: unknown,
+    md: grpc.Metadata,
+    opts: DeadlineOptions,
+    cb: (err: Error | null) => void,
+  ): void;
+  RegisterFunction(
+    req: unknown,
+    md: grpc.Metadata,
+    opts: DeadlineOptions,
+    cb: (err: Error | null) => void,
+  ): void;
+  RegisterConsumerGroup(
+    req: unknown,
+    md: grpc.Metadata,
+    opts: DeadlineOptions,
+    cb: (err: Error | null) => void,
+  ): void;
+  RegisterGroupMember(
+    req: unknown,
+    md: grpc.Metadata,
+    opts: DeadlineOptions,
+    cb: (err: Error | null) => void,
+  ): void;
+  AppendStream(
+    req: unknown,
+    md: grpc.Metadata,
+    opts: DeadlineOptions,
+    cb: (err: Error | null) => void,
+  ): void;
+  WatchRun(
+    req: { run_id: string; key: string; from_sequence: number },
+    md: grpc.Metadata,
+  ): RunWatchStream;
+  close?(): void;
+}
+
+type WorkerServiceConstructor = {
+  new (
+    target: string,
+    credentials: grpc.ChannelCredentials,
+    options: Record<string, unknown>,
+  ): WorkerClient;
+  service: grpc.ServiceDefinition<grpc.UntypedServiceImplementation>;
+};
+
+type ServiceBridgeProtoPackage = {
+  ServiceBridge: new (
+    target: string,
+    credentials: grpc.ChannelCredentials,
+    options: Record<string, string | number>,
+  ) => ControlPlaneClient;
+  ServiceBridgeWorker: WorkerServiceConstructor;
+};
+
+const _sdkRoot = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+  "..",
+);
+const protoPath = join(_sdkRoot, "proto", "servicebridge.proto");
+const servicebridgePackageDefinition = protoLoader.loadSync(protoPath, {
+  keepCase: true,
+  longs: String,
+  enums: String,
+  defaults: true,
+  oneofs: true,
+});
+const proto = grpc.loadPackageDefinition(
+  servicebridgePackageDefinition as Parameters<
+    typeof grpc.loadPackageDefinition
+  >[0],
+) as unknown as { servicebridge: ServiceBridgeProtoPackage };
+const servicebridgeProto = proto.servicebridge;
+
+const channelOpts = {
+  "grpc.max_receive_message_length": -1,
+  "grpc.max_send_message_length": -1,
+  "grpc.http2.initial_window_size": 67108864,
+  "grpc.http2.max_frame_size": 16777216,
+};
+
+// ── RPC Schema ────────────────────────────────────────────────────────────────
+
+/** Тип поля Protobuf-сообщения */
+export type RpcFieldType =
+  | "string"
+  | "int32"
+  | "int64"
+  | "uint32"
+  | "uint64"
+  | "float"
+  | "double"
+  | "bool"
+  | "bytes";
+
+/** Определение одного поля схемы */
+export interface RpcFieldDef {
+  /** Тип поля */
+  type: RpcFieldType;
+  /** Уникальный номер поля (field number в proto) */
+  id: number;
+  /** Повторяющееся поле (массив) */
+  repeated?: boolean;
+}
+
+/** Схема сообщения: имя поля → определение */
+export type RpcSchema = Record<string, RpcFieldDef>;
+
+/** Входная и выходная схемы для RPC-функции */
+export interface RpcSchemaOpts {
+  input?: RpcSchema;
+  output?: RpcSchema;
+}
+
+// Кэш скомпилированных protobuf-типов (ключ = JSON схемы)
+const protoTypeCache = new Map<string, protobufjs.Type>();
+
+function buildProtoType(schema: RpcSchema): protobufjs.Type {
+  const key = JSON.stringify(schema);
+  const cached = protoTypeCache.get(key);
+  if (cached) return cached;
+
+  const root = new protobufjs.Root();
+  const type = new protobufjs.Type("Msg");
+  for (const [fieldName, def] of Object.entries(schema)) {
+    type.add(
+      new protobufjs.Field(
+        fieldName,
+        def.id,
+        def.type,
+        def.repeated ? "repeated" : "optional",
+      ),
+    );
+  }
+  root.add(type);
+  protoTypeCache.set(key, type);
+  return type;
+}
+
+function encodeWithSchema(schema: RpcSchema, payload: unknown): Buffer {
+  const type = buildProtoType(schema);
+  const msg = type.create((payload ?? {}) as Record<string, unknown>);
+  return Buffer.from(type.encode(msg).finish());
+}
+
+function decodeWithSchema(schema: RpcSchema, buf: Buffer): unknown {
+  if (!buf || buf.length === 0) return {};
+  const type = buildProtoType(schema);
+  return type.decode(buf).toJSON();
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+export interface RetryPolicy {
+  retries?: number;
+  retryDelay?: number;
+}
+
+export type WorkerTransport = "tls";
+
+export interface WorkerTLSOpts {
+  caCert?: string | Buffer;
+  cert?: string | Buffer;
+  key?: string | Buffer;
+  serverName?: string;
+}
+
+export interface ServiceBridgeOpts extends RetryPolicy {
+  timeout?: number;
+  /** @deprecated No longer used — discovery is now lazy via LookupFunction. */
+  discoveryTimeout?: number;
+  /**
+   * How often (ms) each SbResolver re-polls LookupFunction to discover new replicas.
+   * Dead replicas are detected instantly by gRPC subchannel health monitoring.
+   * Default: 10 000 ms.
+   */
+  discoveryRefreshMs?: number;
+  queueMaxSize?: number;
+  queueOverflow?: "drop-oldest" | "drop-newest" | "error";
+  heartbeatIntervalMs?: number;
+  workerTransport?: WorkerTransport;
+  /**
+   * Explicit mTLS cert materials for the worker gRPC server.
+   * When omitted, they are provisioned automatically from the server on `serve()`:
+   * the SDK generates a key pair locally and posts the public key to
+   * `POST /api/tls/provision` — the private key never leaves the process.
+   */
+  workerTLS?: WorkerTLSOpts;
+  /**
+   * Base URL for the HTTP admin API used for auto-provisioning and management.
+   * Defaults to the gRPC host on port 14444 (e.g. "http://127.0.0.1:14444").
+   */
+  adminUrl?: string;
+  /**
+   * When `true` (default), automatically patches `console.log / .info / .warn / .error / .debug`
+   * so that all console output is also shipped to ServiceBridge as structured log entries.
+   * Original console output is preserved (pass-through).
+   * Set to `false` to opt out.
+   */
+  captureLogs?: boolean;
+}
+
+export interface RpcOpts extends RetryPolicy {
+  timeout?: number;
+  traceId?: string;
+  parentSpanId?: string;
+}
+
+export interface EventOpts {
+  traceId?: string;
+  parentSpanId?: string;
+  idempotencyKey?: string;
+  headers?: Record<string, string>;
+}
+
+export interface HandleEventOpts {
+  concurrency?: number;
+  prefetch?: number;
+  groupName?: string;
+  retryPolicyJson?: string;
+  /** Server-side filter expression. Syntax: comma-separated AND conditions.
+   * Examples: "status=paid", "amount>100", "status=paid,amount>100", "region!=us-east" */
+  filterExpr?: string;
+}
+
+export interface HandleRpcOpts {
+  timeout?: number;
+  retryable?: boolean;
+  concurrency?: number;
+  /** Схема для авто-валидации и бинарного кодирования payload */
+  schema?: RpcSchemaOpts;
+  /**
+   * Whitelist of service names allowed to call this function.
+   * When set, the worker rejects Handle requests from services not in this list.
+   * Corresponds to the allowed_callers field on the service key.
+   * When mTLS is used, the x-caller-service header is cryptographically backed by the cert CN.
+   */
+  allowedCallers?: string[];
+}
+
+export interface ServeOpts {
+  host?: string;
+  instanceId?: string;
+  weight?: number;
+  transport?: WorkerTransport;
+  tls?: WorkerTLSOpts;
+}
+
+export interface ScheduleOpts {
+  cron?: string;
+  delay?: number;
+  timezone?: string;
+  misfire?: "fire_now" | "skip";
+  via?: "event" | "rpc" | "workflow";
+  retryPolicyJson?: string;
+}
+
+/** StreamWriter allows handlers to push incremental chunks during execution. */
+export interface StreamWriter {
+  /**
+   * Append a chunk to the run's named stream.
+   * @param data   - any JSON-serializable value
+   * @param key    - stream key (default: "default"). Use named keys for multiple streams
+   *                 (e.g. "output", "log", "progress").
+   */
+  write(data: unknown, key?: string): Promise<void>;
+  /**
+   * Signal completion of a named stream (optional — server closes automatically when the run ends).
+   */
+  end(key?: string): Promise<void>;
+}
+
+export interface EventContext {
+  traceId: string;
+  spanId: string;
+  refs: Record<string, string>;
+  retry(delayMs?: number): void;
+  reject(reason: string): void;
+  /** Real-time stream writer. Use ctx.stream.write(data) to push chunks to subscribers. */
+  stream: StreamWriter;
+}
+
+/** Context passed as optional second argument to RPC handlers. */
+export interface RpcContext {
+  traceId: string;
+  spanId: string;
+  /** Real-time stream writer. Use ctx.stream.write(data) to push chunks to subscribers. */
+  stream: StreamWriter;
+}
+
+type EventHandler = (
+  payload: unknown,
+  ctx: EventContext,
+) => void | Promise<void>;
+type FnHandler = (
+  payload: unknown,
+  ctx?: RpcContext,
+) => unknown | Promise<unknown>;
+
+export interface HttpSpan {
+  traceId: string;
+  spanId: string;
+  end(opts: { statusCode?: number; success?: boolean; error?: string }): void;
+}
+
+export interface RunStreamEvent {
+  type: "chunk" | "run_complete";
+  runId: string;
+  key: string;
+  sequence: number;
+  data: unknown;
+  runStatus?: string;
+}
+
+export interface WatchRunOpts {
+  /** Filter by stream key. Empty = all keys. Default: "default". */
+  key?: string;
+  /** Replay chunks with sequence strictly greater than this value. 0 = full replay. */
+  fromSequence?: number;
+}
+
+export type ServiceBridgeErrorSeverity = "fatal" | "retriable" | "ignorable";
+
+export class ServiceBridgeError extends Error {
+  code?: number;
+  component: string;
+  operation: string;
+  severity: ServiceBridgeErrorSeverity;
+  retryable: boolean;
+  override cause?: unknown;
+
+  constructor(opts: {
+    message: string;
+    code?: number;
+    component: string;
+    operation: string;
+    severity: ServiceBridgeErrorSeverity;
+    cause?: unknown;
+  }) {
+    super(opts.message);
+    this.name = "ServiceBridgeError";
+    this.code = opts.code;
+    this.component = opts.component;
+    this.operation = opts.operation;
+    this.severity = opts.severity;
+    this.retryable = opts.severity === "retriable";
+    this.cause = opts.cause;
+  }
+}
+
+/**
+ * A single node in a workflow DAG.
+ *
+ * - `id`    — unique step identifier; used in `deps` of other steps.
+ * - `deps`  — IDs of steps that must succeed before this step runs.
+ *             Empty array (default) = root step; receives the workflow input directly.
+ * - `if`    — optional filter expression (same syntax as event filters).
+ *             If it evaluates to false the step is skipped.
+ */
+export type WorkflowStep =
+  | {
+      id: string;
+      type: "rpc";
+      ref: string;
+      deps?: string[];
+      if?: string;
+      timeoutMs?: number;
+    }
+  | { id: string; type: "event"; ref: string; deps?: string[]; if?: string }
+  | {
+      id: string;
+      type: "event_wait";
+      ref: string;
+      deps?: string[];
+      if?: string;
+      timeoutMs?: number;
+    }
+  | {
+      id: string;
+      type: "sleep";
+      durationMs: number;
+      deps?: string[];
+      if?: string;
+    }
+  | { id: string; type: "workflow"; ref: string; deps?: string[]; if?: string };
+
+export interface ServiceBridgeService {
+  rpc<T = unknown>(fn: string, payload?: unknown, opts?: RpcOpts): Promise<T>;
+  event(topic: string, payload?: unknown, opts?: EventOpts): Promise<string>;
+  job(target: string, opts: ScheduleOpts): Promise<string>;
+  workflow(name: string, steps: WorkflowStep[]): Promise<string>;
+  cancelWorkflowRun(runId: string): Promise<void>;
+  /**
+   * Регистрирует обработчик RPC-функции.
+   * Если передан `opts.schema`, payload автоматически валидируется и
+   * кодируется/декодируется в бинарный Protobuf-формат вместо JSON.
+   * Схема также публикуется в server registry и используется вызывающей стороной.
+   */
+  handleRpc(
+    fn: string,
+    handler: FnHandler,
+    opts?: HandleRpcOpts,
+  ): ServiceBridgeService;
+  handleEvent(
+    pattern: string,
+    handler: EventHandler,
+    opts?: HandleEventOpts,
+  ): ServiceBridgeService;
+  serve(opts?: ServeOpts): Promise<void>;
+  stop(): void;
+  startHttpSpan(opts: {
+    method: string;
+    path: string;
+    traceId?: string;
+    parentSpanId?: string;
+  }): HttpSpan;
+  /**
+   * Register an HTTP endpoint in the ServiceBridge catalog.
+   * Call this once per route after your HTTP server is configured.
+   * The Express and Fastify adapters call this automatically — you only need
+   * this when integrating a different HTTP framework.
+   *
+   * @example
+   * await sb.registerHttpEndpoint({ method: 'GET', route: '/users/:id' });
+   */
+  registerHttpEndpoint(opts: {
+    /** HTTP method: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS */
+    method: string;
+    /** Route pattern including parameter placeholders, e.g. "/users/:id" */
+    route: string;
+    /** Stable identifier for this process instance. Defaults to a per-SDK UUID. */
+    instanceId?: string;
+    /** Address where this service can be reached, e.g. "http://10.0.0.1:3000" */
+    endpoint?: string;
+    /** Service names allowed to call this endpoint (RBAC). Default: [] (all allowed) */
+    allowedCallers?: string[];
+  }): Promise<void>;
+  /**
+   * Subscribe to a run's real-time stream.
+   * Replays existing chunks then forwards new ones until the run completes or the caller breaks.
+   *
+   * @example
+   * const stream = sb.watchRun(runId, { key: "output" });
+   * for await (const chunk of stream) {
+   *   process.stdout.write(chunk.data.token);
+   * }
+   */
+  watchRun(runId: string, opts?: WatchRunOpts): AsyncIterable<RunStreamEvent>;
+  /** @internal Used by captureConsole to forward intercepted log lines. */
+  readonly _log: (
+    level: string,
+    msg: string,
+    attrs?: Record<string, string>,
+  ) => void;
+}
+
+function containsValue(values: string[], value: string): boolean {
+  return values.includes(value);
+}
+
+function containsOrAll(values: string[], value: string): boolean {
+  if (values.length === 0) return true;
+  return containsValue(values, value);
+}
+
+// extractPeerCN reads the mTLS peer certificate CN from a grpc-js server call.
+// Uses the stable getAuthContext() API (ServerUnaryCallImpl, grpc-js ≥1.9).
+function extractPeerCN(call: grpc.ServerUnaryCall<unknown, unknown>): string {
+  // Use the stable getAuthContext() API (available since grpc-js 1.9, ServerUnaryCallImpl).
+  const cert = (
+    call as grpc.ServerUnaryCall<unknown, unknown> & {
+      getAuthContext?(): { sslPeerCertificate?: { subject?: { CN?: string } } };
+    }
+  ).getAuthContext?.()?.sslPeerCertificate;
+  return typeof cert?.subject?.CN === "string" ? cert.subject.CN : "";
+}
+
+function computeDurationMs(startedAt: number): number {
+  return Math.max(1, Date.now() - startedAt);
+}
+
+function toJsonBuffer(payload: unknown): Buffer {
+  return Buffer.from(JSON.stringify(payload ?? {}));
+}
+
+function toPemBuffer(v?: string | Buffer): Buffer | undefined {
+  if (!v) return undefined;
+  return Buffer.isBuffer(v) ? v : Buffer.from(v);
+}
+
+function severityFromStatus(code?: number): ServiceBridgeErrorSeverity {
+  switch (code) {
+    case grpc.status.UNAVAILABLE:
+    case grpc.status.UNKNOWN:
+    case grpc.status.DEADLINE_EXCEEDED:
+    case grpc.status.RESOURCE_EXHAUSTED:
+      return "retriable";
+    case grpc.status.CANCELLED:
+      return "ignorable";
+    default:
+      return "fatal";
+  }
+}
+
+function normalizeServiceError(
+  err: unknown,
+  operation: string,
+  component = "control-plane",
+): ServiceBridgeError {
+  if (err instanceof ServiceBridgeError) {
+    return err;
+  }
+  const grpcErr = err as Partial<grpc.ServiceError> | undefined;
+  const code = typeof grpcErr?.code === "number" ? grpcErr.code : undefined;
+  const message =
+    typeof grpcErr?.message === "string" && grpcErr.message.length > 0
+      ? grpcErr.message
+      : err instanceof Error
+        ? err.message
+        : String(err);
+  return new ServiceBridgeError({
+    message,
+    code,
+    component,
+    operation,
+    severity: severityFromStatus(code),
+    cause: err,
+  });
+}
+
+function reportSDKError(
+  operation: string,
+  err: unknown,
+  component = "sdk",
+): ServiceBridgeError {
+  const normalized = normalizeServiceError(err, operation, component);
+  const message = `[servicebridge] ${normalized.component}.${normalized.operation}: ${normalized.message}`;
+  if (normalized.severity === "fatal") {
+    console.error(message, err);
+  } else {
+    console.warn(message, err);
+  }
+  return normalized;
+}
+
+function _secretEquals(a: string, b: string): boolean {
+  const sumA = crypto.createHash("sha256").update(a).digest();
+  const sumB = crypto.createHash("sha256").update(b).digest();
+  return crypto.timingSafeEqual(sumA, sumB);
+}
+
+function parseCanonicalFunctionName(target: string): {
+  canonicalName: string;
+  serviceName: string;
+  fnName: string;
+} | null {
+  const canonicalName = target.trim();
+  if (!canonicalName) return null;
+  const slash = canonicalName.indexOf("/");
+  if (slash <= 0 || slash === canonicalName.length - 1) return null;
+  const serviceName = canonicalName.slice(0, slash).trim();
+  const fnName = canonicalName.slice(slash + 1).trim();
+  if (!serviceName || !fnName) return null;
+  return { canonicalName, serviceName, fnName };
+}
+
+function _resolveWorkerEndpoint(endpoint: string): string {
+  const raw = endpoint.trim();
+  if (!raw) throw new Error("worker endpoint is empty");
+  if (raw.includes("://")) {
+    throw new Error("worker endpoint must be host:port without scheme");
+  }
+  return raw;
+}
+
+function workerChannelOptions(
+  tlsOpts?: WorkerTLSOpts,
+): Record<string, string | number> {
+  if (!tlsOpts?.serverName) {
+    return channelOpts;
+  }
+  return {
+    ...channelOpts,
+    "grpc.ssl_target_name_override": tlsOpts.serverName,
+    "grpc.default_authority": tlsOpts.serverName,
+  };
+}
+
+function workerClientCredentials(
+  tlsOpts?: WorkerTLSOpts,
+): grpc.ChannelCredentials {
+  return grpc.credentials.createSsl(
+    toPemBuffer(tlsOpts?.caCert),
+    toPemBuffer(tlsOpts?.key),
+    toPemBuffer(tlsOpts?.cert),
+  );
+}
+
+// ── TLS auto-provisioning (Variant B.1) ───────────────────────────────────────
+// SDK generates an ECDSA key pair locally. Only the public key is sent to the
+// server. The server signs it and returns cert + CA PEM. Private key never leaves
+// this process.
+
+async function provisionWorkerTLS(
+  adminBase: string,
+  serviceKey: string,
+  _serviceName: string,
+): Promise<{ cert: Buffer; key: Buffer; caCert: Buffer }> {
+  const { privateKey, publicKey } = crypto.generateKeyPairSync("ec", {
+    namedCurve: "P-256",
+    privateKeyEncoding: { type: "pkcs8", format: "pem" },
+    publicKeyEncoding: { type: "spki", format: "pem" },
+  });
+
+  const res = await fetch(`${adminBase}/api/tls/provision`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-service-key": serviceKey,
+    },
+    body: JSON.stringify({ public_key_pem: publicKey }),
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(
+      `TLS provisioning failed (${res.status}): ${body}. ` +
+        `Make sure the service key "${serviceKey.slice(0, 12)}…" has a service_name set in the UI.`,
+    );
+  }
+
+  const data = (await res.json()) as { cert_pem?: string; ca_pem?: string };
+  if (!data.cert_pem || !data.ca_pem) {
+    throw new Error(
+      "TLS provisioning: server returned incomplete response (missing cert_pem or ca_pem)",
+    );
+  }
+
+  return {
+    cert: Buffer.from(data.cert_pem),
+    key: Buffer.from(privateKey as string),
+    caCert: Buffer.from(data.ca_pem),
+  };
+}
+
+// ── gRPC Custom Name Resolver for sb:// scheme ────────────────────────────────
+// Each servicebridge() call registers its context keyed by a unique clientId.
+// gRPC channels use target `sb://<clientId>/<canonical-fn-name>`, which routes
+// through this resolver.  The resolver calls LookupFunction on first resolution
+// and re-resolves on a background timer (Stale-While-Revalidate pattern).
+// gRPC's native subchannel health monitoring handles dead-worker detection instantly.
+
+type SbEndpointInfo = { host: string; port: number };
+
+interface SbResolverContext {
+  lookupFn: (target: string) => Promise<SbEndpointInfo[]>;
+  refreshIntervalMs: number;
+}
+
+const _sbContexts = new Map<string, SbResolverContext>();
+let _sbResolverRegistered = false;
+
+function ensureSbResolverRegistered(): void {
+  if (_sbResolverRegistered) return;
+  _sbResolverRegistered = true;
+
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { registerResolver } = require("@grpc/grpc-js/build/src/resolver") as {
+    registerResolver: (scheme: string, cls: unknown) => void;
+  };
+
+  class SbResolver {
+    private readonly clientId: string;
+    private readonly canonicalName: string;
+    private readonly listener: (
+      endpoints: unknown,
+      attrs: Record<string, unknown>,
+      serviceConfig: null,
+      note: string,
+    ) => boolean;
+    private refreshTimer: ReturnType<typeof setInterval> | null = null;
+
+    constructor(
+      target: { authority?: string; path: string },
+      listener: SbResolver["listener"],
+    ) {
+      this.clientId = target.authority ?? "";
+      // path may be "/canonical-name" (with leading slash) or "canonical-name"
+      this.canonicalName = (target.path ?? "").replace(/^\/+/, "");
+      this.listener = listener;
+      this.init().catch(() => {});
+    }
+
+    private async init(): Promise<void> {
+      const ctx = _sbContexts.get(this.clientId);
+      if (!ctx) {
+        this.listener(
+          {
+            ok: false,
+            error: {
+              code: 14,
+              details: `No SB context for clientId=${this.clientId}`,
+              metadata: {},
+            },
+          },
+          {},
+          null,
+          "sb-resolver",
+        );
+        return;
+      }
+      // Background timer: re-resolve on every tick so new replicas are discovered
+      // without a streaming connection. Dead replicas are caught immediately by
+      // gRPC's native subchannel health probing.
+      this.refreshTimer = setInterval(
+        () => this.resolve().catch(() => {}),
+        ctx.refreshIntervalMs,
+      );
+      await this.resolve();
+    }
+
+    updateResolution(): void {
+      this.resolve().catch(() => {});
+    }
+
+    private async resolve(): Promise<void> {
+      const ctx = _sbContexts.get(this.clientId);
+      if (!ctx) return;
+      try {
+        const eps = await ctx.lookupFn(this.canonicalName);
+        this.reportEndpoints(eps);
+      } catch {
+        // gRPC will call updateResolution() again on the next connection attempt
+      }
+    }
+
+    private reportEndpoints(eps: SbEndpointInfo[]): void {
+      if (eps.length === 0) {
+        this.listener(
+          {
+            ok: false,
+            error: {
+              code: 14,
+              details: `No live endpoints for ${this.canonicalName}`,
+              metadata: {},
+            },
+          },
+          {},
+          null,
+          "sb-resolver",
+        );
+        return;
+      }
+      this.listener(
+        { ok: true, value: eps.map((ep) => ({ addresses: [ep] })) },
+        {},
+        null,
+        "sb-resolver",
+      );
+    }
+
+    destroy(): void {
+      if (this.refreshTimer) {
+        clearInterval(this.refreshTimer);
+        this.refreshTimer = null;
+      }
+    }
+
+    static getDefaultAuthority(target: {
+      authority?: string;
+      path: string;
+    }): string {
+      return target.authority ?? target.path ?? "";
+    }
+  }
+
+  registerResolver("sb", SbResolver);
+}
+
+export function servicebridge(
+  url: string,
+  serviceKey: string,
+  service = "",
+  globalOpts: ServiceBridgeOpts = {},
+): ServiceBridgeService {
+  const meta = new grpc.Metadata();
+  meta.add("x-service-key", serviceKey);
+
+  const rawUrl = url.trim();
+  const target = rawUrl.replace(/^grpcs?:\/\//, "") || "127.0.0.1:14445";
+
+  // Derive the HTTP admin base URL (used for TLS provisioning and management).
+  // Default: same host as gRPC but on port 14444.
+  const adminBase =
+    globalOpts.adminUrl ??
+    (rawUrl
+      ? rawUrl.replace(/^grpcs?:\/\//, "http://").replace(/:\d+$/, ":14444")
+      : "http://127.0.0.1:14444");
+
+  const configuredCACert = toPemBuffer(globalOpts.workerTLS?.caCert);
+  const configuredClientKey = toPemBuffer(globalOpts.workerTLS?.key);
+  const configuredClientCert = toPemBuffer(globalOpts.workerTLS?.cert);
+
+  if (
+    (configuredClientCert && !configuredClientKey) ||
+    (!configuredClientCert && configuredClientKey)
+  ) {
+    throw new Error(
+      "workerTLS.cert and workerTLS.key must be provided together",
+    );
+  }
+
+  // Control plane uses one-way TLS: server presents its cert, we authenticate
+  // via x-service-key in gRPC metadata. No client cert required here.
+  // If the user provided an explicit CA cert, we use it for server verification;
+  // otherwise we skip server cert verification (safe for local dev with self-signed CAs).
+  function makeControlPlaneCreds(): grpc.ChannelCredentials {
+    if (configuredCACert) {
+      // One-way TLS: verify server cert with provided CA, no client cert.
+      return grpc.credentials.createSsl(configuredCACert, null, null);
+    }
+    // Skip server cert verification — suitable for local dev with self-signed CA.
+    return grpc.credentials.createSsl(null, null, null, {
+      checkServerIdentity: () => undefined,
+    });
+  }
+
+  function unaryDeadlineOptions(
+    timeoutMs = globalOpts.timeout ?? 30_000,
+  ): DeadlineOptions {
+    return { deadline: new Date(Date.now() + timeoutMs) };
+  }
+
+  // Unique client ID — used as the authority in `sb://<clientId>/<fn>` targets
+  // so the module-level SbResolver can find this client's context.
+  const clientId = crypto.randomUUID();
+
+  // Effective mTLS materials — set from explicit workerTLS or auto-provisioned in serve().
+  // Declared here so _controlReady closure can reference it before the normal var declaration.
+  let effectiveWorkerTLS: WorkerTLSOpts | null = globalOpts.workerTLS ?? null;
+
+  // The stub is created lazily after TLS provisioning.
+  // Until _controlReady resolves, all SDK calls are held in the offline queue.
+  let stub = new servicebridgeProto.ServiceBridge(
+    target,
+    makeControlPlaneCreds(),
+    workerChannelOptions(globalOpts.workerTLS),
+  );
+
+  // If no explicit certs are provided, provision them now (eagerly, in the background).
+  // The stub is recreated with the provisioned CA cert once provisioning completes.
+  // startRegistryWatch() is called only after the stub is ready.
+  const _controlReady: Promise<void> = (async () => {
+    if (configuredCACert) {
+      // CA cert already provided — stub creds are correct, connect immediately.
+      return;
+    }
+    // Provision: generate key pair, POST public key to server, get cert+CA back.
+    try {
+      const prov = await provisionWorkerTLS(adminBase, serviceKey, service);
+      effectiveWorkerTLS = prov;
+      // Recreate stub with verified server CA cert (one-way TLS).
+      try {
+        (stub as { close?: () => void }).close?.();
+      } catch {
+        /* ignore */
+      }
+      stub = new servicebridgeProto.ServiceBridge(
+        target,
+        grpc.credentials.createSsl(prov.caCert, null, null),
+        workerChannelOptions(prov),
+      );
+    } catch (_err) {
+      // Provisioning failure is non-fatal for client-only mode (no serve()).
+      // Errors will surface when actual gRPC calls are attempted.
+    }
+  })();
+
+  type EventHandlerEntry = {
+    groupName: string;
+    pattern: string;
+    handler: EventHandler;
+    opts: HandleEventOpts;
+  };
+
+  const eventHandlers = new Map<string, EventHandlerEntry>();
+  const fnHandlers = new Map<
+    string,
+    { handler: FnHandler; opts: HandleRpcOpts }
+  >();
+  const registeredGroups = new Set<string>();
+
+  // ── Lightweight registry: metadata only, no connection state ──────────────
+  // gRPC channels (via SbResolver) own connection management.
+  interface FunctionMeta {
+    canonicalName: string;
+    serviceName: string;
+    fnName: string;
+    endpoints: SbEndpointInfo[];
+    inputSchema?: RpcSchema;
+    outputSchema?: RpcSchema;
+    allowedCallers: string[];
+  }
+  const functionMeta = new Map<string, FunctionMeta>();
+  // shortName → canonical (null = ambiguous: multiple services export same fn name)
+  const fnAliasMap = new Map<string, string | null>();
+  // One grpc.Channel per canonical function name; owned by gRPC via SbResolver
+  const functionChannels = new Map<string, grpc.Channel>();
+
+  let isOnline = false;
+  let stopped = false;
+  // Timer to restore isOnline after transient control-plane connection errors.
+  let onlineRestoreTimer: ReturnType<typeof setTimeout> | null = null;
+
+  type QueuedOp =
+    | { type: "event"; topic: string; payload: unknown; opts?: EventOpts }
+    | { type: "job"; target: string; opts: ScheduleOpts }
+    | { type: "workflow"; name: string; steps: WorkflowStep[] }
+    | {
+        type: "reportCallStart";
+        traceId: string;
+        spanId: string;
+        parentSpanId: string;
+        fn: string;
+        startedAt: number;
+        inputBuf: Buffer;
+        attempt: number;
+      }
+    | {
+        type: "reportCall";
+        traceId: string;
+        spanId: string;
+        fn: string;
+        startedAt: number;
+        inputBuf: Buffer;
+        success: boolean;
+        attempt: number;
+        outputBuf?: Buffer;
+        error?: string;
+      };
+
+  const offlineQueue: QueuedOp[] = [];
+  let workerServer: grpc.Server | null = null;
+  let serveState: {
+    endpoint: string;
+    transport: WorkerTransport;
+    opts: ServeOpts;
+    instanceId: string;
+  } | null = null;
+  let heartbeatTimer: ReturnType<typeof setTimeout> | null = null;
+  let registrationSyncPromise: Promise<void> | null = null;
+  let lastCpuSample: { user: number; system: number } | null = null;
+  let lastCpuTime = 0;
+
+  function getProcessMetrics(): { cpuPercent?: number; ramMb?: number } {
+    const ramMb = Math.round(process.memoryUsage().rss / (1024 * 1024));
+    const now = Date.now();
+    const cpu = process.cpuUsage();
+    let cpuPercent: number | undefined;
+    if (lastCpuSample && lastCpuTime > 0) {
+      const elapsedMs = now - lastCpuTime;
+      if (elapsedMs >= 100) {
+        const deltaUser = cpu.user - lastCpuSample.user;
+        const deltaSystem = cpu.system - lastCpuSample.system;
+        cpuPercent = Math.min(
+          100,
+          Math.max(0, (deltaUser + deltaSystem) / (elapsedMs * 10)),
+        );
+      }
+    }
+    lastCpuSample = { user: cpu.user, system: cpu.system };
+    lastCpuTime = now;
+    return { cpuPercent, ramMb };
+  }
+
+  function enqueueOffline(op: QueuedOp): void {
+    const max = globalOpts.queueMaxSize ?? 1000;
+    const policy = globalOpts.queueOverflow ?? "drop-oldest";
+    if (offlineQueue.length >= max) {
+      if (policy === "error")
+        throw new Error("ServiceBridge offline queue is full");
+      if (policy === "drop-oldest") {
+        offlineQueue.shift();
+      } else {
+        return;
+      }
+    }
+    offlineQueue.push(op);
+  }
+
+  function makeWorkerMeta(): grpc.Metadata {
+    const md = new grpc.Metadata();
+    md.add("x-caller-service", service);
+    return md;
+  }
+
+  async function sendReportCallStart(op: {
+    traceId: string;
+    spanId: string;
+    parentSpanId: string;
+    fn: string;
+    startedAt: number;
+    inputBuf: Buffer;
+    attempt: number;
+  }): Promise<void> {
+    await new Promise<void>((resolve, reject) => {
+      stub.ReportCallStart(
+        {
+          trace_id: op.traceId,
+          span_id: op.spanId,
+          parent_span_id: op.parentSpanId,
+          fn: op.fn,
+          service_name: service,
+          started_at: String(op.startedAt),
+          input: op.inputBuf,
+          attempt: op.attempt,
+          instance_id: serveState?.instanceId ?? "",
+        },
+        meta,
+        unaryDeadlineOptions(),
+        (err: Error | null) => (err ? reject(err) : resolve()),
+      );
+    });
+  }
+
+  async function sendReportCall(op: {
+    traceId: string;
+    spanId: string;
+    fn: string;
+    startedAt: number;
+    inputBuf: Buffer;
+    success: boolean;
+    attempt: number;
+    outputBuf?: Buffer;
+    error?: string;
+  }): Promise<void> {
+    await new Promise<void>((resolve, reject) => {
+      stub.ReportCall(
+        {
+          trace_id: op.traceId,
+          span_id: op.spanId,
+          fn: op.fn,
+          service_name: service,
+          started_at: String(op.startedAt),
+          duration_ms: String(computeDurationMs(op.startedAt)),
+          success: op.success,
+          error: op.error ?? "",
+          input: op.inputBuf,
+          output: op.outputBuf ?? Buffer.alloc(0),
+          attempt: op.attempt,
+          instance_id: serveState?.instanceId ?? "",
+        },
+        meta,
+        unaryDeadlineOptions(),
+        (err: Error | null) => (err ? reject(err) : resolve()),
+      );
+    });
+  }
+
+  // ── Logger (batched log shipping to ServiceBridge) ──────────────────────────
+  type LogEntry = {
+    trace_id?: string;
+    span_id?: string;
+    service_name: string;
+    level: string;
+    message: string;
+    timestamp_ns: string;
+    attributes: Record<string, string>;
+    instance_id?: string;
+  };
+
+  let logBatch: LogEntry[] = [];
+  let logFlushTimer: ReturnType<typeof setTimeout> | null = null;
+
+  function flushLogs(): void {
+    if (logBatch.length === 0) return;
+    const entries = logBatch;
+    logBatch = [];
+    if (logFlushTimer !== null) {
+      clearTimeout(logFlushTimer);
+      logFlushTimer = null;
+    }
+    stub.ReportLog({ entries }, meta, unaryDeadlineOptions(), () => {});
+  }
+
+  function pushLog(
+    level: string,
+    msg: string,
+    attrs?: Record<string, string>,
+  ): void {
+    const tc = traceStorage.getStore();
+    const entry: LogEntry = {
+      service_name: service,
+      level,
+      message: msg,
+      timestamp_ns: String(Date.now() * 1_000_000),
+      attributes: attrs ?? {},
+    };
+    if (tc?.traceId) entry.trace_id = tc.traceId;
+    if (tc?.spanId) entry.span_id = tc.spanId;
+    if (serveState?.instanceId) entry.instance_id = serveState.instanceId;
+    logBatch.push(entry);
+    if (logBatch.length >= 100) {
+      flushLogs();
+    } else if (logFlushTimer === null) {
+      logFlushTimer = setTimeout(flushLogs, 500);
+    }
+  }
+
+  // ── Registry context registration ──────────────────────────────────────────
+  ensureSbResolverRegistered();
+  _sbContexts.set(clientId, {
+    lookupFn: async (target: string) => {
+      const canonical = resolveCanonical(target);
+      if (canonical) {
+        const m = functionMeta.get(canonical);
+        if (m && m.endpoints.length > 0) return m.endpoints;
+      }
+      return doLookupFunction(target);
+    },
+    refreshIntervalMs: globalOpts.discoveryRefreshMs ?? 10_000,
+  });
+
+  // ── Helper: parse raw wire endpoints into SbEndpointInfo[] ─────────────────
+  function parseEndpointsFromWire(raw: unknown): SbEndpointInfo[] {
+    if (!Array.isArray(raw)) return [];
+    const results: SbEndpointInfo[] = [];
+    for (const ep of raw) {
+      const str = typeof ep?.endpoint === "string" ? ep.endpoint.trim() : "";
+      if (!str) continue;
+      const colon = str.lastIndexOf(":");
+      if (colon < 0) continue;
+      const host = str.slice(0, colon);
+      const port = parseInt(str.slice(colon + 1), 10);
+      if (host && Number.isFinite(port) && port > 0)
+        results.push({ host, port });
+    }
+    return results;
+  }
+
+  function parseSchemaJsonSafe(raw: unknown): RpcSchema | undefined {
+    if (typeof raw !== "string" || !raw) return undefined;
+    try {
+      const p = JSON.parse(raw);
+      if (p && typeof p === "object" && !Array.isArray(p))
+        return p as RpcSchema;
+    } catch {
+      /* ignored */
+    }
+    return undefined;
+  }
+
+  // ── Resolve a call target to a canonical function name ─────────────────────
+  function resolveCanonical(target: string): string | null {
+    const n = target.trim();
+    if (!n) throw new Error("RPC target is required");
+    if (n.includes("/")) return functionMeta.has(n) ? n : null;
+    const alias = fnAliasMap.get(n);
+    if (alias === null)
+      throw new Error(
+        `RPC target "${n}" is ambiguous; use canonical service/fn`,
+      );
+    return alias ?? null;
+  }
+
+  // ── Server-side lazy lookup (called by resolver on cache miss) ───────────────
+  async function doLookupFunction(target: string): Promise<SbEndpointInfo[]> {
+    return new Promise((resolve) => {
+      stub.LookupFunction(
+        { fn_name: target },
+        meta,
+        { deadline: new Date(Date.now() + 5_000) },
+        (err, res) => {
+          if (err || !res?.found) {
+            resolve([]);
+            return;
+          }
+          const canonicalName = res.canonical_name ?? target;
+          const wire = res.endpoints as RegistryFunctionWire | undefined;
+          const endpoints = parseEndpointsFromWire(wire?.endpoints);
+          // Upsert into local metadata so next resolveCanonical() finds it
+          const isNewFunction = !functionMeta.has(canonicalName);
+          if (isNewFunction) {
+            const parsed = parseCanonicalFunctionName(canonicalName);
+            if (parsed) {
+              functionMeta.set(canonicalName, {
+                canonicalName,
+                fnName: parsed.fnName,
+                serviceName: parsed.serviceName,
+                inputSchema: parseSchemaJsonSafe(wire?.input_schema_json),
+                outputSchema: parseSchemaJsonSafe(wire?.output_schema_json),
+                allowedCallers: Array.isArray(wire?.allowed_callers)
+                  ? (wire.allowed_callers as string[])
+                  : [],
+                endpoints,
+              });
+              rebuildAliasMap();
+            }
+          } else {
+            const meta = functionMeta.get(canonicalName);
+            if (meta) meta.endpoints = endpoints;
+          }
+          resolve(endpoints);
+        },
+      );
+    });
+  }
+
+  // ── Registry rebuild helpers ────────────────────────────────────────────────
+  function rebuildAliasMap(): void {
+    fnAliasMap.clear();
+    const count = new Map<string, number>();
+    for (const m of functionMeta.values())
+      count.set(m.fnName, (count.get(m.fnName) ?? 0) + 1);
+    for (const m of functionMeta.values())
+      fnAliasMap.set(
+        m.fnName,
+        (count.get(m.fnName) ?? 0) === 1 ? m.canonicalName : null,
+      );
+  }
+
+  // ── gRPC channel per function (resolver manages endpoint selection + LB) ────
+  function getOrCreateFunctionChannel(canonicalName: string): grpc.Channel {
+    let ch = functionChannels.get(canonicalName);
+    if (!ch) {
+      const tlsOpts = effectiveWorkerTLS;
+      const creds = tlsOpts
+        ? workerClientCredentials(tlsOpts)
+        : grpc.credentials.createSsl(null, null, null, {
+            checkServerIdentity: () => undefined,
+          });
+      // `sb://<clientId>/<canonical>` — SbResolver looks up context by clientId
+      ch = new grpc.Channel(`sb://${clientId}/${canonicalName}`, creds, {
+        ...workerChannelOptions(tlsOpts ?? undefined),
+        "grpc.lb_policy_name": "round_robin",
+      });
+      functionChannels.set(canonicalName, ch);
+    }
+    return ch;
+  }
+
+  function closeAllFunctionChannels(): void {
+    for (const [, ch] of functionChannels) {
+      try {
+        ch.close();
+      } catch {
+        /* ignored */
+      }
+    }
+    functionChannels.clear();
+  }
+
+  // Set online once the control plane stub has valid creds and flush any queued ops.
+  _controlReady
+    .then(() => {
+      isOnline = true;
+      flushQueue().catch((err) => {
+        if (isConnectionError(err)) scheduleOnlineRestore();
+        else reportSDKError("flush-on-ready", err);
+      });
+    })
+    .catch(() => {
+      // Provisioning failure is non-fatal for client-only mode.
+      // isOnline remains false; individual calls will surface errors.
+    });
+
+  // Restore isOnline after transient control-plane errors (gRPC reconnects automatically).
+  function scheduleOnlineRestore(): void {
+    if (stopped || isOnline || onlineRestoreTimer) return;
+    onlineRestoreTimer = setTimeout(() => {
+      onlineRestoreTimer = null;
+      if (!stopped) {
+        isOnline = true;
+        flushQueue().catch((err) => {
+          if (isConnectionError(err)) scheduleOnlineRestore();
+          else reportSDKError("flush-on-restore", err);
+        });
+      }
+    }, 2_000);
+  }
+
+  function isConnectionError(e: unknown): boolean {
+    const code = (e as Partial<grpc.ServiceError> | undefined)?.code;
+    return code === grpc.status.UNAVAILABLE || code === grpc.status.UNKNOWN;
+  }
+
+  function normalizeUnknownErrorMessage(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
+  }
+
+  function reportCallStartAsync(
+    traceId: string,
+    spanId: string,
+    parentSpanId: string,
+    fn: string,
+    startedAt: number,
+    inputBuf: Buffer,
+    attempt: number,
+  ): void {
+    if (!isOnline) {
+      enqueueOffline({
+        type: "reportCallStart",
+        traceId,
+        spanId,
+        parentSpanId,
+        fn,
+        startedAt,
+        inputBuf,
+        attempt,
+      });
+      return;
+    }
+    sendReportCallStart({
+      traceId,
+      spanId,
+      parentSpanId,
+      fn,
+      startedAt,
+      inputBuf,
+      attempt,
+    }).catch((err) => {
+      if (isConnectionError(err)) {
+        isOnline = false;
+        scheduleOnlineRestore();
+        enqueueOffline({
+          type: "reportCallStart",
+          traceId,
+          spanId,
+          parentSpanId,
+          fn,
+          startedAt,
+          inputBuf,
+          attempt,
+        });
+        return;
+      }
+      reportSDKError("report-call-start", err);
+    });
+  }
+
+  function reportCallAsync(
+    traceId: string,
+    spanId: string,
+    fn: string,
+    startedAt: number,
+    inputBuf: Buffer,
+    success: boolean,
+    attempt: number,
+    outputBuf?: Buffer,
+    error = "",
+  ): void {
+    if (!isOnline) {
+      enqueueOffline({
+        type: "reportCall",
+        traceId,
+        spanId,
+        fn,
+        startedAt,
+        inputBuf,
+        success,
+        attempt,
+        outputBuf,
+        error,
+      });
+      return;
+    }
+    sendReportCall({
+      traceId,
+      spanId,
+      fn,
+      startedAt,
+      inputBuf,
+      success,
+      attempt,
+      outputBuf,
+      error,
+    }).catch((err) => {
+      if (isConnectionError(err)) {
+        isOnline = false;
+        scheduleOnlineRestore();
+        enqueueOffline({
+          type: "reportCall",
+          traceId,
+          spanId,
+          fn,
+          startedAt,
+          inputBuf,
+          success,
+          attempt,
+          outputBuf,
+          error,
+        });
+        return;
+      }
+      reportSDKError("report-call", err);
+    });
+  }
+
+  async function flushQueue(): Promise<void> {
+    while (offlineQueue.length > 0 && isOnline) {
+      const op = offlineQueue[0];
+      try {
+        if (op.type === "event") {
+          await new Promise<void>((res, rej) => {
+            stub.Publish(
+              {
+                topic: op.topic,
+                payload: toJsonBuffer(op.payload),
+                headers: op.opts?.headers ?? {},
+                trace_id: op.opts?.traceId ?? "",
+                parent_span_id: op.opts?.parentSpanId ?? "",
+                producer_service: service,
+                idempotency_key: op.opts?.idempotencyKey ?? "",
+              },
+              meta,
+              unaryDeadlineOptions(),
+              (err: Error | null) => (err ? rej(err) : res()),
+            );
+          });
+        } else if (op.type === "job") {
+          await new Promise<void>((res, rej) => {
+            stub.RegisterJob(
+              {
+                cron_expr: op.opts.cron ?? "",
+                timezone: op.opts.timezone ?? "UTC",
+                misfire_policy: op.opts.misfire ?? "fire_now",
+                target_type: op.opts.via ?? "rpc",
+                target_ref: op.target,
+                delay_ms: op.opts.delay ?? 0,
+                service_name: service,
+                retry_policy_json: op.opts.retryPolicyJson ?? "{}",
+              },
+              meta,
+              unaryDeadlineOptions(),
+              (err: Error | null) => (err ? rej(err) : res()),
+            );
+          });
+        } else if (op.type === "workflow") {
+          await new Promise<void>((res, rej) => {
+            stub.RegisterWorkflow(
+              {
+                name: op.name,
+                definition: JSON.stringify(op.steps),
+                opts: "{}",
+                service_name: service,
+              },
+              meta,
+              unaryDeadlineOptions(),
+              (err: Error | null) => (err ? rej(err) : res()),
+            );
+          });
+        } else if (op.type === "reportCallStart") {
+          await sendReportCallStart({ ...op });
+        } else if (op.type === "reportCall") {
+          await sendReportCall(op);
+        }
+        offlineQueue.shift();
+      } catch (err) {
+        if (isConnectionError(err)) {
+          isOnline = false;
+          scheduleOnlineRestore();
+          break;
+        }
+        reportSDKError("flush-offline-queue", err);
+        // Keep queue head for retry on next reconnect.
+        break;
+      }
+    }
+  }
+
+  function requirePeerCN(
+    call: grpc.ServerUnaryCall<
+      WorkerHandleRequest | WorkerDeliverRequest,
+      unknown
+    >,
+    allowedCallers: string[] | undefined,
+    isDeliver: boolean,
+  ): string | null {
+    const peerCN = extractPeerCN(call);
+    if (!peerCN) return null;
+    if (isDeliver) {
+      return peerCN === "ServiceBridge Server" ? peerCN : null;
+    }
+    if (peerCN === "ServiceBridge Server") return peerCN;
+    if (allowedCallers && allowedCallers.length > 0) {
+      return containsValue(allowedCallers, peerCN) ? peerCN : null;
+    }
+    return peerCN;
+  }
+
+  function isRegistryResyncRequiredError(e: unknown): boolean {
+    const code = (e as Partial<grpc.ServiceError> | undefined)?.code;
+    return (
+      code === grpc.status.NOT_FOUND || code === grpc.status.FAILED_PRECONDITION
+    );
+  }
+
+  async function sendHeartbeat(): Promise<void> {
+    if (!serveState) return;
+    const state = serveState;
+    const metrics = getProcessMetrics();
+    const req: Record<string, unknown> = {
+      service_name: service,
+      instance_id: state.instanceId,
+      endpoint: state.endpoint,
+      group_names: [...registeredGroups],
+      function_names: [...fnHandlers.keys()],
+      transport: state.transport,
+    };
+    if (metrics.cpuPercent != null) req.cpu_percent = metrics.cpuPercent;
+    if (metrics.ramMb != null) req.ram_mb = metrics.ramMb;
+    await new Promise<void>((resolve, reject) => {
+      stub.Heartbeat(req, meta, unaryDeadlineOptions(), (err: Error | null) =>
+        err ? reject(normalizeServiceError(err, "heartbeat")) : resolve(),
+      );
+    });
+  }
+
+  async function syncRegistrations(reason: string): Promise<void> {
+    if (!serveState) return;
+    if (registrationSyncPromise) {
+      return registrationSyncPromise;
+    }
+
+    const state = serveState;
+    registrationSyncPromise = (async () => {
+      const nextGroups = new Set<string>();
+      for (const [fn, fnEntry] of fnHandlers.entries()) {
+        await new Promise<void>((resolve, reject) => {
+          stub.RegisterFunction(
+            {
+              fn_name: fn,
+              service_name: service,
+              instance_id: state.instanceId,
+              endpoint: state.endpoint,
+              transport: state.transport,
+              weight: Math.max(1, state.opts.weight ?? 1),
+              input_schema_json: fnEntry.opts.schema?.input
+                ? JSON.stringify(fnEntry.opts.schema.input)
+                : "",
+              output_schema_json: fnEntry.opts.schema?.output
+                ? JSON.stringify(fnEntry.opts.schema.output)
+                : "",
+            },
+            meta,
+            unaryDeadlineOptions(),
+            (err: Error | null) =>
+              err
+                ? reject(
+                    normalizeServiceError(
+                      err,
+                      `register-function:${reason}:${fn}`,
+                    ),
+                  )
+                : resolve(),
+          );
+        });
+      }
+
+      for (const entry of eventHandlers.values()) {
+        const groupName = entry.groupName;
+        await new Promise<void>((resolve, reject) => {
+          stub.RegisterConsumerGroup(
+            {
+              name: groupName,
+              pattern: entry.pattern,
+              mode: "shared",
+              retry_policy_json: entry.opts.retryPolicyJson ?? "{}",
+              active: true,
+              filter_expr: entry.opts.filterExpr ?? "",
+            },
+            meta,
+            unaryDeadlineOptions(),
+            (err: Error | null) =>
+              err
+                ? reject(
+                    normalizeServiceError(
+                      err,
+                      `register-group:${reason}:${groupName}`,
+                    ),
+                  )
+                : resolve(),
+          );
+        });
+        await new Promise<void>((resolve, reject) => {
+          stub.RegisterGroupMember(
+            {
+              group_name: groupName,
+              service_name: service,
+              instance_id: state.instanceId,
+              endpoint: state.endpoint,
+              transport: state.transport,
+              weight: Math.max(1, state.opts.weight ?? 1),
+            },
+            meta,
+            unaryDeadlineOptions(),
+            (err: Error | null) =>
+              err
+                ? reject(
+                    normalizeServiceError(
+                      err,
+                      `register-member:${reason}:${groupName}`,
+                    ),
+                  )
+                : resolve(),
+          );
+        });
+        nextGroups.add(groupName);
+      }
+
+      registeredGroups.clear();
+      for (const groupName of nextGroups) {
+        registeredGroups.add(groupName);
+      }
+      await sendHeartbeat();
+    })().finally(() => {
+      registrationSyncPromise = null;
+    });
+
+    return registrationSyncPromise;
+  }
+
+  function nextHeartbeatDelayMs(): number {
+    const base = Math.max(1_000, globalOpts.heartbeatIntervalMs ?? 10_000);
+    const jitter = Math.max(250, Math.floor(base * 0.2));
+    const offset = Math.floor(Math.random() * (jitter * 2 + 1)) - jitter;
+    return Math.max(1_000, base + offset);
+  }
+
+  async function heartbeatTick(): Promise<void> {
+    if (!serveState || stopped) return;
+    try {
+      await sendHeartbeat();
+    } catch (err) {
+      if (isConnectionError(err)) {
+        isOnline = false;
+        scheduleOnlineRestore();
+      } else if (isRegistryResyncRequiredError(err)) {
+        await syncRegistrations("heartbeat-resync");
+      } else {
+        reportSDKError("heartbeat", err);
+      }
+    } finally {
+      if (!stopped && serveState) {
+        scheduleNextHeartbeat();
+      }
+    }
+  }
+
+  function scheduleNextHeartbeat(delayMs = nextHeartbeatDelayMs()): void {
+    if (!serveState || stopped) return;
+    if (heartbeatTimer) clearTimeout(heartbeatTimer);
+    heartbeatTimer = setTimeout(() => {
+      heartbeatTimer = null;
+      heartbeatTick().catch((err) => {
+        reportSDKError("heartbeat", err);
+      });
+    }, delayMs);
+  }
+
+  function makeStreamWriter(runId: string): StreamWriter {
+    const append = (data: unknown, key = "default"): Promise<void> => {
+      if (!isOnline || !runId) return Promise.resolve();
+      return new Promise<void>((resolve, reject) => {
+        stub.AppendStream(
+          {
+            run_id: runId,
+            key,
+            data: Buffer.from(JSON.stringify(data)),
+          },
+          meta,
+          unaryDeadlineOptions(),
+          (err: Error | null) =>
+            err
+              ? reject(normalizeServiceError(err, `append-stream:${runId}`))
+              : resolve(),
+        );
+      });
+    };
+    return {
+      write: append,
+      end: (_key = "default") => Promise.resolve(),
+    };
+  }
+
+  async function handleRpc(
+    call: grpc.ServerUnaryCall<WorkerHandleRequest, WorkerHandleResponse>,
+    cb: grpc.sendUnaryData<WorkerHandleResponse>,
+  ) {
+    const entry = fnHandlers.get(call.request.fn || "");
+    const allowedCallers = entry?.opts.allowedCallers;
+    if (!requirePeerCN(call, allowedCallers, false)) {
+      cb({
+        code: grpc.status.UNAUTHENTICATED,
+        message: "mTLS client cert required",
+      });
+      return;
+    }
+    const { fn, payload: payloadBuf, trace_id, span_id } = call.request;
+    const traceCtx: TraceCtx = {
+      traceId: trace_id || "",
+      spanId: span_id || "",
+    };
+
+    if (!entry) {
+      cb({
+        code: grpc.status.NOT_FOUND,
+        message: `No handler registered for: ${fn}`,
+        metadata: new grpc.Metadata(),
+      });
+      return;
+    }
+
+    // Worker-side caller policy: peerCN verified by requirePeerCN above.
+    const _callerAllowList = entry.opts.allowedCallers;
+    const _peerCN = extractPeerCN(call) ?? "";
+
+    // Декодируем: protobuf если у handler есть входная схема, иначе JSON
+    let parsed: unknown = {};
+    const inputSchema = entry.opts.schema?.input;
+    const outputSchema = entry.opts.schema?.output;
+    try {
+      if (payloadBuf?.length) {
+        parsed = inputSchema
+          ? decodeWithSchema(inputSchema, payloadBuf as Buffer)
+          : JSON.parse((payloadBuf as Buffer).toString());
+      }
+    } catch {
+      cb({
+        code: grpc.status.INVALID_ARGUMENT,
+        message: "Invalid payload encoding",
+      });
+      return;
+    }
+
+    const rpcCtx: RpcContext = {
+      traceId: traceCtx.traceId,
+      spanId: traceCtx.spanId,
+      stream: makeStreamWriter(traceCtx.traceId),
+    };
+
+    try {
+      const result = await traceStorage.run(traceCtx, () =>
+        entry.handler(parsed, rpcCtx),
+      );
+      // Кодируем: protobuf если есть выходная схема, иначе JSON
+      const outputBuf = outputSchema
+        ? encodeWithSchema(outputSchema, result)
+        : toJsonBuffer(result);
+      cb(null, { output: outputBuf, success: true });
+    } catch (e: unknown) {
+      cb(null, {
+        output: Buffer.alloc(0),
+        success: false,
+        error: normalizeUnknownErrorMessage(e),
+      });
+    }
+  }
+
+  async function handleDeliverMessage(
+    call: grpc.ServerUnaryCall<WorkerDeliverRequest, WorkerDeliverResponse>,
+    cb: grpc.sendUnaryData<WorkerDeliverResponse>,
+  ): Promise<void> {
+    if (!requirePeerCN(call, undefined, true)) {
+      cb({
+        code: grpc.status.UNAUTHENTICATED,
+        message: "mTLS client cert required (ServiceBridge Server)",
+      });
+      return;
+    }
+    const { group_name, payload, trace_id, parent_span_id } = call.request;
+    const traceCtx: TraceCtx = {
+      traceId: trace_id || "",
+      spanId: parent_span_id || "",
+    };
+    const entry =
+      typeof group_name === "string"
+        ? eventHandlers.get(group_name)
+        : undefined;
+    if (!entry) {
+      cb(null, { ack: false, error: "consumer_group_handler_missing" });
+      return;
+    }
+
+    let parsed: unknown = {};
+    try {
+      if (payload?.length) parsed = JSON.parse((payload as Buffer).toString());
+    } catch {
+      cb(null, { ack: false, reject_reason: "invalid_json_payload" });
+      return;
+    }
+
+    let shouldRetry = false;
+    let retryAfter = 1000;
+    let rejectReason = "";
+    const errors: string[] = [];
+
+    const ctx: EventContext = {
+      traceId: traceCtx.traceId,
+      spanId: traceCtx.spanId,
+      refs: {
+        topic: String(call.request?.topic ?? ""),
+        groupName: entry.groupName,
+        messageId: String(call.request?.message_id ?? ""),
+        attempt: String(call.request?.attempt ?? ""),
+        headers: JSON.stringify(call.request?.headers ?? {}),
+      },
+      retry(delayMs = 1000) {
+        shouldRetry = true;
+        retryAfter = Math.max(1, Math.floor(delayMs));
+      },
+      reject(reason: string) {
+        rejectReason = reason || "rejected_by_consumer";
+      },
+      stream: makeStreamWriter(traceCtx.traceId),
+    };
+
+    try {
+      await traceStorage.run(traceCtx, () => entry.handler(parsed, ctx));
+    } catch (e: unknown) {
+      errors.push(normalizeUnknownErrorMessage(e));
+      shouldRetry = true;
+    }
+
+    if (rejectReason) {
+      cb(null, {
+        ack: false,
+        reject_reason: rejectReason,
+        error: errors.join("; "),
+      });
+      return;
+    }
+    if (shouldRetry || errors.length > 0) {
+      cb(null, {
+        ack: false,
+        retry_after_ms: retryAfter,
+        error: errors.join("; ").slice(0, 2048),
+      });
+      return;
+    }
+    cb(null, { ack: true });
+  }
+
+  const svc: ServiceBridgeService = {
+    async rpc<T = unknown>(
+      fn: string,
+      payload?: unknown,
+      opts?: RpcOpts,
+    ): Promise<T> {
+      try {
+        await _controlReady;
+      } catch (err) {
+        throw normalizeServiceError(err, "control-plane");
+      }
+      const tc = traceStorage.getStore();
+      const traceId = opts?.traceId ?? tc?.traceId ?? crypto.randomUUID();
+      const maxRetries = opts?.retries ?? globalOpts.retries ?? 3;
+      const baseDelay = opts?.retryDelay ?? globalOpts.retryDelay ?? 300;
+      const timeout = opts?.timeout ?? globalOpts.timeout ?? 30000;
+
+      // Resolve canonical name — check local metadata first, then server lookup.
+      let canonical = resolveCanonical(fn);
+      if (!canonical) {
+        await doLookupFunction(fn);
+        canonical = resolveCanonical(fn);
+      }
+      if (!canonical)
+        throw normalizeServiceError(
+          new Error(`No endpoints available for RPC: ${fn}`),
+          `rpc:${fn}`,
+          "worker",
+        );
+
+      const fmeta = functionMeta.get(canonical);
+
+      // Caller-side policy check
+      if (fmeta && !containsOrAll(fmeta.allowedCallers, service)) {
+        throw new Error(
+          `Service "${service}" is not allowed to call "${fn}". ` +
+            `Permitted callers: ${fmeta.allowedCallers.join(", ")}`,
+        );
+      }
+
+      const inputSchema = fmeta?.inputSchema;
+      const outputSchema = fmeta?.outputSchema;
+      const inputBuf = inputSchema
+        ? encodeWithSchema(inputSchema, payload)
+        : toJsonBuffer(payload);
+      const telemetryInputBuf = toJsonBuffer(payload);
+
+      // Root span — represents the entire RPC call including all retry attempts.
+      // When retries are configured (maxRetries > 0), each attempt also gets its
+      // own child span named "attempt:<canonical>" so the UI can render them as
+      // individual retry rows (same model as workflow retries).
+      const rootSpanId = crypto.randomUUID();
+      const parentSpanId = opts?.parentSpanId ?? tc?.spanId ?? "";
+      const rootStartedAt = Date.now();
+      const hasRetries = maxRetries > 0;
+
+      // Report root span start once (covers all attempts).
+      reportCallStartAsync(
+        traceId,
+        rootSpanId,
+        parentSpanId,
+        canonical,
+        rootStartedAt,
+        telemetryInputBuf,
+        1,
+      );
+
+      // gRPC channel for this function — SbResolver handles LB + connection pool
+      const channel = getOrCreateFunctionChannel(canonical);
+      const workerClient = new servicebridgeProto.ServiceBridgeWorker(
+        "__channel__",
+        grpc.credentials.createInsecure(),
+        { channelOverride: channel },
+      ) as unknown as WorkerClient;
+
+      let lastError: unknown;
+      for (let attempt = 1; attempt <= maxRetries + 1; attempt++) {
+        // When retrying: each attempt is a child span of the root span.
+        // When no retries configured: the root span IS the only span (current behavior).
+        const attemptSpanId = hasRetries ? crypto.randomUUID() : rootSpanId;
+        const attemptParentId = hasRetries ? rootSpanId : parentSpanId;
+        const attemptFn = hasRetries ? `attempt:${canonical}` : canonical;
+        const attemptStartedAt = hasRetries ? Date.now() : rootStartedAt;
+
+        if (hasRetries) {
+          reportCallStartAsync(
+            traceId,
+            attemptSpanId,
+            attemptParentId,
+            attemptFn,
+            attemptStartedAt,
+            telemetryInputBuf,
+            attempt,
+          );
+        }
+
+        try {
+          const deadline = new Date(Date.now() + timeout);
+          // Send the short function name (e.g. "td.echo") to the worker, not the
+          // canonical name (e.g. "dev0/td.echo") — workers register handlers by
+          // short name and can't find them by canonical.
+          const fn = fmeta?.fnName ?? canonical;
+          if (!fn) throw new Error("unreachable");
+          const res = await new Promise<WorkerHandleResponse>(
+            (resolve, reject) => {
+              workerClient.Handle(
+                {
+                  fn,
+                  payload: inputBuf,
+                  trace_id: traceId,
+                  span_id: attemptSpanId,
+                },
+                makeWorkerMeta(),
+                // waitForReady: gRPC holds the call in CONNECTING state until a
+                // subchannel becomes READY (bounded by deadline). This transparently
+                // survives worker restarts without needing manual retry logic.
+                { deadline, waitForReady: true },
+                (err: Error | null, response?: WorkerHandleResponse) =>
+                  err
+                    ? reject(err)
+                    : resolve(
+                        response ?? { success: false, error: "empty response" },
+                      ),
+              );
+            },
+          );
+          if (!res?.success)
+            throw new Error(res?.error || "handler returned failure");
+          const outputBuf = res.output ?? Buffer.alloc(0);
+          const result = outputSchema
+            ? decodeWithSchema(outputSchema, outputBuf)
+            : outputBuf?.length
+              ? JSON.parse(outputBuf.toString())
+              : {};
+
+          const encodedOutput = outputBuf?.length
+            ? toJsonBuffer(result)
+            : Buffer.alloc(0);
+          if (hasRetries) {
+            // Close attempt span as success (with its own input+output).
+            reportCallAsync(
+              traceId,
+              attemptSpanId,
+              attemptFn,
+              attemptStartedAt,
+              telemetryInputBuf,
+              true,
+              attempt,
+              encodedOutput,
+            );
+            // Close root span as overall success — propagate output from the successful attempt.
+            reportCallAsync(
+              traceId,
+              rootSpanId,
+              canonical,
+              rootStartedAt,
+              telemetryInputBuf,
+              true,
+              attempt,
+              encodedOutput,
+            );
+          } else {
+            reportCallAsync(
+              traceId,
+              rootSpanId,
+              canonical,
+              rootStartedAt,
+              telemetryInputBuf,
+              true,
+              attempt,
+              encodedOutput,
+            );
+          }
+          return result as T;
+        } catch (e: unknown) {
+          lastError = e;
+          const errMsg = normalizeUnknownErrorMessage(e);
+          if (hasRetries) {
+            // Close attempt span as failure.
+            reportCallAsync(
+              traceId,
+              attemptSpanId,
+              attemptFn,
+              attemptStartedAt,
+              telemetryInputBuf,
+              false,
+              attempt,
+              undefined,
+              errMsg,
+            );
+            if (attempt > maxRetries) {
+              // Last attempt exhausted — close root span as failure too.
+              reportCallAsync(
+                traceId,
+                rootSpanId,
+                canonical,
+                rootStartedAt,
+                telemetryInputBuf,
+                false,
+                attempt,
+                undefined,
+                errMsg,
+              );
+            }
+          } else {
+            // gRPC channel handles connection recovery automatically;
+            // no manual eviction needed.
+            reportCallAsync(
+              traceId,
+              rootSpanId,
+              canonical,
+              rootStartedAt,
+              telemetryInputBuf,
+              false,
+              attempt,
+              undefined,
+              errMsg,
+            );
+          }
+          if (attempt <= maxRetries) {
+            await new Promise((r) =>
+              setTimeout(r, baseDelay * 2 ** (attempt - 1)),
+            );
+          }
+        }
+      }
+      throw normalizeServiceError(lastError, `rpc:${fn}`, "worker");
+    },
+
+    event(topic: string, payload?: unknown, opts?: EventOpts): Promise<string> {
+      if (!isOnline) {
+        enqueueOffline({ type: "event", topic, payload, opts });
+        return Promise.resolve("");
+      }
+      const tc = traceStorage.getStore();
+      return new Promise((resolve, reject) => {
+        stub.Publish(
+          {
+            topic,
+            payload: toJsonBuffer(payload),
+            headers: opts?.headers ?? {},
+            trace_id: opts?.traceId ?? tc?.traceId ?? "",
+            parent_span_id: opts?.parentSpanId ?? tc?.spanId ?? "",
+            producer_service: service,
+            idempotency_key: opts?.idempotencyKey ?? "",
+          },
+          meta,
+          unaryDeadlineOptions(),
+          (err: Error | null, res?: { message_id?: string }) =>
+            err
+              ? reject(normalizeServiceError(err, `publish:${topic}`))
+              : resolve(res?.message_id ?? ""),
+        );
+      });
+    },
+
+    handleRpc(
+      fn: string,
+      handler: FnHandler,
+      opts?: HandleRpcOpts,
+    ): ServiceBridgeService {
+      fnHandlers.set(fn, { handler, opts: opts ?? {} });
+      return svc;
+    },
+
+    handleEvent(
+      pattern: string,
+      handler: EventHandler,
+      opts?: HandleEventOpts,
+    ): ServiceBridgeService {
+      const normalizedOpts = opts ?? {};
+      const groupName = normalizedOpts.groupName || `${service}:${pattern}`;
+      if (eventHandlers.has(groupName)) {
+        throw new Error(
+          `Duplicate event consumer group "${groupName}". ` +
+            "Use a distinct groupName for each handleEvent() registration.",
+        );
+      }
+      eventHandlers.set(groupName, {
+        groupName,
+        pattern,
+        handler,
+        opts: normalizedOpts,
+      });
+      return svc;
+    },
+
+    async serve(opts: ServeOpts = {}): Promise<void> {
+      if (workerServer) throw new Error("serve() already called");
+      if (fnHandlers.size === 0 && eventHandlers.size === 0) {
+        throw new Error(
+          "No handlers registered. Call handleRpc() or handleEvent() before serve().",
+        );
+      }
+      if (!service.trim()) {
+        throw new Error("serve() requires a non-empty service name");
+      }
+
+      try {
+        workerServer = new grpc.Server(channelOpts);
+        workerServer.addService(
+          servicebridgeProto.ServiceBridgeWorker.service,
+          {
+            Handle: handleRpc,
+            DeliverMessage: handleDeliverMessage,
+          },
+        );
+        const host = opts.host || "127.0.0.1";
+        const requestedTransport = opts.transport ?? globalOpts.workerTransport;
+
+        // Resolve effective TLS options: explicit opts → global workerTLS → auto-provision.
+        const tlsOpts = opts.tls ?? globalOpts.workerTLS;
+        let effectiveCert = toPemBuffer(tlsOpts?.cert);
+        let effectiveKey = toPemBuffer(tlsOpts?.key);
+        let effectiveCACert = toPemBuffer(tlsOpts?.caCert);
+
+        if (!effectiveCert || !effectiveKey || !effectiveCACert) {
+          // Reuse cert provisioned during _controlReady if available — avoids issuing two
+          // separate key pairs for the same service instance (wasteful and confusing in logs).
+          const cached = effectiveWorkerTLS;
+          if (cached?.cert && cached?.key && cached?.caCert) {
+            effectiveCert = toPemBuffer(cached.cert);
+            effectiveKey = toPemBuffer(cached.key);
+            effectiveCACert = toPemBuffer(cached.caCert);
+          } else {
+            // Auto-provision: generate key pair locally, post public key to server.
+            // Private key stays in this process — server only sees the public key.
+            const provisioned = await provisionWorkerTLS(
+              adminBase,
+              serviceKey,
+              service,
+            );
+            effectiveCert = provisioned.cert;
+            effectiveKey = provisioned.key;
+            effectiveCACert = provisioned.caCert;
+            effectiveWorkerTLS = {
+              caCert: effectiveCACert,
+              cert: effectiveCert,
+              key: effectiveKey,
+            };
+          }
+        }
+
+        if (!effectiveKey || !effectiveCert) {
+          throw new Error("TLS key and cert are required for worker serve()");
+        }
+        const workerTransport: WorkerTransport = requestedTransport ?? "tls";
+        const serverCreds = grpc.ServerCredentials.createSsl(
+          effectiveCACert ?? null, // verify ServiceBridge's client cert against the shared CA
+          [{ private_key: effectiveKey, cert_chain: effectiveCert }],
+          true, // require mTLS — only ServiceBridge (CN="ServiceBridge Server") may call workers
+        );
+        const port = await new Promise<number>((resolve, reject) => {
+          const server = workerServer;
+          if (!server) {
+            reject(new Error("Worker server is not initialized"));
+            return;
+          }
+          server.bindAsync(`${host}:0`, serverCreds, (err, p) =>
+            err ? reject(err) : resolve(p),
+          );
+        });
+        const endpoint = `${host}:${port}`;
+        const instanceId =
+          opts.instanceId ||
+          Array.from(crypto.getRandomValues(new Uint8Array(3)))
+            .map((b) => b.toString(16).padStart(2, "0"))
+            .join(""); // 6 hex chars
+        serveState = { endpoint, transport: workerTransport, opts, instanceId };
+
+        await syncRegistrations("initial");
+        scheduleNextHeartbeat();
+
+        await _controlReady;
+      } catch (err) {
+        if (heartbeatTimer) clearTimeout(heartbeatTimer);
+        heartbeatTimer = null;
+        registeredGroups.clear();
+        serveState = null;
+        workerServer?.forceShutdown();
+        workerServer = null;
+        throw normalizeServiceError(err, "serve");
+      }
+    },
+
+    stop(): void {
+      stopped = true;
+      isOnline = false;
+      if (onlineRestoreTimer) clearTimeout(onlineRestoreTimer);
+      if (heartbeatTimer) clearTimeout(heartbeatTimer);
+      onlineRestoreTimer = null;
+      heartbeatTimer = null;
+      registeredGroups.clear();
+
+      flushLogs();
+
+      closeAllFunctionChannels();
+      functionMeta.clear();
+      fnAliasMap.clear();
+      _sbContexts.delete(clientId);
+      offlineQueue.length = 0;
+      workerServer?.forceShutdown();
+      workerServer = null;
+      serveState = null;
+      try {
+        stub.close?.();
+      } catch (err) {
+        reportSDKError("close-control-plane-client", err);
+      }
+    },
+
+    job(target: string, opts: ScheduleOpts): Promise<string> {
+      if (!isOnline) {
+        enqueueOffline({ type: "job", target, opts });
+        return Promise.resolve("");
+      }
+      return new Promise((resolve, reject) => {
+        stub.RegisterJob(
+          {
+            cron_expr: opts.cron ?? "",
+            timezone: opts.timezone ?? "UTC",
+            misfire_policy: opts.misfire ?? "fire_now",
+            target_type: opts.via ?? "rpc",
+            target_ref: target,
+            delay_ms: opts.delay ?? 0,
+            service_name: service,
+            retry_policy_json: opts.retryPolicyJson ?? "{}",
+          },
+          meta,
+          unaryDeadlineOptions(),
+          (err: Error | null, res?: { id?: string }) =>
+            err
+              ? reject(normalizeServiceError(err, `register-job:${target}`))
+              : resolve(res?.id ?? ""),
+        );
+      });
+    },
+
+    workflow(name: string, steps: WorkflowStep[]): Promise<string> {
+      if (!isOnline) {
+        enqueueOffline({ type: "workflow", name, steps });
+        return Promise.resolve("");
+      }
+      return new Promise((resolve, reject) => {
+        stub.RegisterWorkflow(
+          {
+            name,
+            definition: JSON.stringify(steps),
+            opts: "{}",
+            service_name: service,
+          },
+          meta,
+          unaryDeadlineOptions(),
+          (err: Error | null, res?: { id?: string }) =>
+            err
+              ? reject(normalizeServiceError(err, `register-workflow:${name}`))
+              : resolve(res?.id ?? ""),
+        );
+      });
+    },
+
+    async cancelWorkflowRun(runId: string): Promise<void> {
+      // Derive the HTTP admin URL from the gRPC URL by switching the protocol
+      // and using the well-known HTTP port (7700 default).
+      const adminBase =
+        globalOpts.adminUrl ??
+        rawUrl.replace(/:\d+$/, ":7700").replace(/^grpcs?:\/\//, "http://");
+      const endpoint = `${adminBase}/api/workflow-runs/${encodeURIComponent(runId)}`;
+      const res = await fetch(endpoint, { method: "DELETE" });
+      if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`cancelWorkflowRun failed (${res.status}): ${body}`);
+      }
+    },
+
+    startHttpSpan(opts: {
+      method: string;
+      path: string;
+      traceId?: string;
+      parentSpanId?: string;
+    }): HttpSpan {
+      const tc = traceStorage.getStore();
+      const traceId = opts.traceId ?? tc?.traceId ?? crypto.randomUUID();
+      const spanId = crypto.randomUUID();
+      const parentSpanId = opts.parentSpanId ?? tc?.spanId ?? "";
+      const fn = `http:${opts.method}:${opts.path}`;
+      const startedAt = Date.now();
+      const inputBuf = toJsonBuffer({ method: opts.method, path: opts.path });
+      reportCallStartAsync(
+        traceId,
+        spanId,
+        parentSpanId,
+        fn,
+        startedAt,
+        inputBuf,
+        1,
+      );
+      return {
+        traceId,
+        spanId,
+        end(endOpts) {
+          const success =
+            endOpts.success ??
+            (endOpts.statusCode != null && endOpts.statusCode < 400);
+          const outputBuf = toJsonBuffer({
+            statusCode: endOpts.statusCode ?? null,
+            error: endOpts.error ?? null,
+          });
+          reportCallAsync(
+            traceId,
+            spanId,
+            fn,
+            startedAt,
+            inputBuf,
+            success,
+            1,
+            outputBuf,
+            endOpts.error ?? "",
+          );
+        },
+      };
+    },
+
+    async registerHttpEndpoint(opts: {
+      method: string;
+      route: string;
+      instanceId?: string;
+      endpoint?: string;
+      allowedCallers?: string[];
+    }): Promise<void> {
+      const res = await fetch(`${adminBase}/api/http/register`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-service-key": serviceKey,
+        },
+        body: JSON.stringify({
+          service_name: service,
+          method: opts.method,
+          route_pattern: opts.route,
+          instance_id: opts.instanceId,
+          endpoint: opts.endpoint,
+          allowed_callers: opts.allowedCallers ?? [],
+        }),
+      });
+      if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`registerHttpEndpoint failed (${res.status}): ${body}`);
+      }
+    },
+
+    watchRun(
+      runId: string,
+      opts?: WatchRunOpts,
+    ): AsyncIterable<RunStreamEvent> {
+      const key = opts?.key ?? "default";
+      const fromSeq = opts?.fromSequence ?? 0;
+      const WATCH_RUN_QUEUE_LIMIT = 256;
+      const WATCH_RUN_RETRY_MIN_MS = 500;
+      const WATCH_RUN_RETRY_MAX_MS = 5_000;
+
+      return {
+        [Symbol.asyncIterator](): AsyncIterator<RunStreamEvent> {
+          let stream: RunWatchStream | null = null;
+          let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+          let cancelled = false;
+          let done = false;
+          let fatalError: ServiceBridgeError | null = null;
+          let reconnectDelay = WATCH_RUN_RETRY_MIN_MS;
+          let lastSequence = fromSeq;
+          const queue: RunStreamEvent[] = [];
+          const waiters: Array<{
+            resolve: (value: IteratorResult<RunStreamEvent>) => void;
+            reject: (reason?: unknown) => void;
+          }> = [];
+
+          function metadataValue(
+            err: unknown,
+            keyName: string,
+          ): string | undefined {
+            const metadata = (err as { metadata?: grpc.Metadata } | undefined)
+              ?.metadata;
+            if (!metadata || typeof metadata.get !== "function")
+              return undefined;
+            const values = metadata.get(keyName);
+            if (!Array.isArray(values) || values.length === 0) return undefined;
+            const value = values[0];
+            if (typeof value === "string") return value;
+            if (Buffer.isBuffer(value)) return value.toString();
+            return value == null ? undefined : String(value);
+          }
+
+          function parseChunk(chunk: RunChunkWire): RunStreamEvent {
+            let data: unknown = null;
+            const rawData = chunk.data
+              ? Buffer.from(chunk.data)
+              : Buffer.alloc(0);
+            if (rawData.length > 0) {
+              try {
+                data = JSON.parse(rawData.toString());
+              } catch (cause) {
+                throw new ServiceBridgeError({
+                  message: `watchRun received non-JSON chunk for ${runId}`,
+                  component: "sdk",
+                  operation: `watch-run:${runId}`,
+                  severity: "fatal",
+                  cause,
+                });
+              }
+            }
+            return {
+              type: chunk.type === "run_complete" ? "run_complete" : "chunk",
+              runId,
+              key: chunk.key || key,
+              sequence: Number(chunk.sequence ?? 0),
+              data,
+              runStatus: chunk.run_status || undefined,
+            };
+          }
+
+          function clearReconnectTimer() {
+            if (reconnectTimer) {
+              clearTimeout(reconnectTimer);
+              reconnectTimer = null;
+            }
+          }
+
+          function clearStream(cancelCurrent = false) {
+            const current = stream;
+            stream = null;
+            if (!current) return;
+            if (typeof current.removeAllListeners === "function") {
+              current.removeAllListeners();
+            }
+            if (cancelCurrent && typeof current.cancel === "function") {
+              current.cancel();
+            }
+          }
+
+          function fail(err: ServiceBridgeError) {
+            if (fatalError || done) return;
+            fatalError = err;
+            clearReconnectTimer();
+            clearStream(true);
+            for (const waiter of waiters) {
+              waiter.reject(err);
+            }
+            waiters.length = 0;
+          }
+
+          function enqueue(event: RunStreamEvent) {
+            if (fatalError || done) return;
+            if (waiters.length > 0) {
+              const waiter = waiters.shift();
+              if (waiter) {
+                waiter.resolve({ value: event, done: false });
+              }
+              return;
+            }
+
+            if (queue.length >= WATCH_RUN_QUEUE_LIMIT) {
+              fail(
+                new ServiceBridgeError({
+                  message: `watchRun consumer is not draining fast enough for ${runId}`,
+                  component: "sdk",
+                  operation: `watch-run:${runId}`,
+                  severity: "fatal",
+                }),
+              );
+              return;
+            }
+
+            queue.push(event);
+          }
+
+          function finish() {
+            if (done || fatalError) return;
+            done = true;
+            clearReconnectTimer();
+            clearStream(false);
+            for (const waiter of waiters) {
+              waiter.resolve({ value: undefined, done: true });
+            }
+            waiters.length = 0;
+          }
+
+          function shouldRetry(err: unknown): boolean {
+            if (
+              metadataValue(err, "servicebridge-run-stream-retryable") ===
+              "true"
+            ) {
+              return true;
+            }
+            const code = (err as Partial<grpc.ServiceError> | undefined)?.code;
+            return (
+              code === grpc.status.UNAVAILABLE ||
+              code === grpc.status.UNKNOWN ||
+              code === grpc.status.DEADLINE_EXCEEDED ||
+              code === grpc.status.RESOURCE_EXHAUSTED
+            );
+          }
+
+          function maybeUpdateResumeSequence(err: unknown) {
+            const parsed = Number(
+              metadataValue(err, "servicebridge-run-stream-resume-from") ?? 0,
+            );
+            if (Number.isFinite(parsed) && parsed > lastSequence) {
+              lastSequence = parsed;
+            }
+          }
+
+          function scheduleReconnect() {
+            if (cancelled || done || fatalError || reconnectTimer) return;
+            const delay = reconnectDelay;
+            reconnectTimer = setTimeout(() => {
+              reconnectTimer = null;
+              start();
+            }, delay);
+            reconnectDelay = Math.min(
+              reconnectDelay * 2,
+              WATCH_RUN_RETRY_MAX_MS,
+            );
+          }
+
+          function start() {
+            if (cancelled || done || fatalError || stream) return;
+
+            try {
+              const current = stub.WatchRun(
+                { run_id: runId, key, from_sequence: lastSequence },
+                meta,
+              );
+              let endedWithOK = false;
+              stream = current;
+
+              current.on("data", (chunk: RunChunkWire) => {
+                if (stream !== current || cancelled || done || fatalError)
+                  return;
+                reconnectDelay = WATCH_RUN_RETRY_MIN_MS;
+
+                let event: RunStreamEvent;
+                try {
+                  event = parseChunk(chunk);
+                } catch (err) {
+                  fail(
+                    err instanceof ServiceBridgeError
+                      ? err
+                      : normalizeServiceError(err, `watch-run:${runId}`),
+                  );
+                  return;
+                }
+                if (event.sequence > 0) {
+                  if (event.sequence <= lastSequence) return;
+                  lastSequence = event.sequence;
+                }
+
+                enqueue(event);
+                if (event.type === "run_complete") {
+                  finish();
+                }
+              });
+
+              current.on("error", (err: unknown) => {
+                if (stream !== current || cancelled || done || fatalError)
+                  return;
+                clearStream(false);
+                maybeUpdateResumeSequence(err);
+                if (!shouldRetry(err)) {
+                  fail(normalizeServiceError(err, `watch-run:${runId}`));
+                  return;
+                }
+                reconnectDelay = metadataValue(
+                  err,
+                  "servicebridge-run-stream-disconnect-reason",
+                )
+                  ? WATCH_RUN_RETRY_MIN_MS
+                  : reconnectDelay;
+                scheduleReconnect();
+              });
+
+              current.on("status", (statusInfo: { code?: number }) => {
+                if (
+                  (stream !== current && stream !== null) ||
+                  cancelled ||
+                  done ||
+                  fatalError
+                ) {
+                  return;
+                }
+                endedWithOK = statusInfo.code === grpc.status.OK;
+                if (endedWithOK) {
+                  clearReconnectTimer();
+                  if (stream === null) {
+                    finish();
+                  }
+                }
+              });
+
+              current.on("end", () => {
+                if (stream !== current || cancelled || done || fatalError)
+                  return;
+                clearStream(false);
+                if (endedWithOK) {
+                  finish();
+                  return;
+                }
+                scheduleReconnect();
+              });
+            } catch (err) {
+              maybeUpdateResumeSequence(err);
+              if (!shouldRetry(err)) {
+                fail(normalizeServiceError(err, `watch-run:${runId}`));
+                return;
+              }
+              scheduleReconnect();
+            }
+          }
+
+          start();
+
+          return {
+            next(): Promise<IteratorResult<RunStreamEvent>> {
+              if (queue.length > 0) {
+                const value = queue.shift();
+                if (value) {
+                  return Promise.resolve({ value, done: false });
+                }
+              }
+              if (fatalError) {
+                return Promise.reject(fatalError);
+              }
+              if (done) {
+                return Promise.resolve({ value: undefined, done: true });
+              }
+              return new Promise((resolve, reject) => {
+                waiters.push({ resolve, reject });
+              });
+            },
+            return(): Promise<IteratorResult<RunStreamEvent>> {
+              cancelled = true;
+              clearReconnectTimer();
+              clearStream(true);
+              if (!done && !fatalError) {
+                done = true;
+                for (const waiter of waiters) {
+                  waiter.resolve({ value: undefined, done: true });
+                }
+                waiters.length = 0;
+              }
+              return Promise.resolve({ value: undefined, done: true });
+            },
+          };
+        },
+      };
+    },
+
+    _log: (level, msg, attrs) => pushLog(level, msg, attrs),
+  };
+
+  if (globalOpts.captureLogs !== false) {
+    captureConsole(svc);
+  }
+
+  return svc;
+}
+
+// ── Console interception ──────────────────────────────────────────────────────
+
+type ConsoleMethod = "log" | "info" | "warn" | "error" | "debug";
+
+/**
+ * Intercepts `console.log / .info / .warn / .error / .debug` so that every
+ * call is **also** shipped to ServiceBridge as a structured log entry.
+ *
+ * Original console output is preserved (pass-through) — nothing changes on
+ * the terminal side. Trace correlation works automatically via AsyncLocalStorage.
+ *
+ * @example
+ * const svc = servicebridge("localhost:14445", "my-key", "orders");
+ * captureConsole(svc); // call once at startup
+ * console.log("order created"); // appears on stdout AND in ServiceBridge
+ */
+export function captureConsole(svc: ServiceBridgeService): void {
+  const levelMap: Record<ConsoleMethod, string> = {
+    log: "INFO",
+    info: "INFO",
+    warn: "WARN",
+    error: "ERROR",
+    debug: "DEBUG",
+  };
+
+  const methods: ConsoleMethod[] = ["log", "info", "warn", "error", "debug"];
+
+  for (const method of methods) {
+    const original = console[method].bind(console);
+    const sbLevel = levelMap[method];
+
+    console[method] = (...args: unknown[]) => {
+      // Always pass through to the original console
+      original(...args);
+
+      // Separate string/primitive args (→ message) from object args (→ attributes).
+      // This preserves structure so the server can index and filter by fields.
+      let message = "";
+      const attributes: Record<string, string> = {};
+
+      for (const a of args) {
+        if (a === null || a === undefined) {
+          // skip nullish values
+        } else if (typeof a === "string") {
+          message = message ? `${message} ${a}` : a;
+        } else if (a instanceof Error) {
+          const errStr = a.stack ?? a.message;
+          message = message ? `${message} ${errStr}` : errStr;
+        } else if (typeof a === "object" && !Array.isArray(a)) {
+          // Plain object → merge fields into attributes (stringify non-strings)
+          for (const [k, v] of Object.entries(a as Record<string, unknown>)) {
+            if (v === null || v === undefined) continue;
+            attributes[k] = typeof v === "string" ? v : JSON.stringify(v);
+          }
+        } else {
+          // Primitives (number, boolean, array) → append to message
+          const s =
+            typeof a === "object"
+              ? (() => {
+                  try {
+                    return JSON.stringify(a);
+                  } catch {
+                    return String(a);
+                  }
+                })()
+              : String(a);
+          message = message ? `${message} ${s}` : s;
+        }
+      }
+
+      if (message || Object.keys(attributes).length > 0) {
+        svc._log(
+          sbLevel,
+          message,
+          Object.keys(attributes).length > 0 ? attributes : undefined,
+        );
+      }
+    };
+  }
+}