service-bridge 1.9.0-dev.52 → 2.0.0-alpha.1

package/README.md

@@ -1,1337 +1,633 @@
-<!-- keywords: service-bridge servicebridge npm install service-bridge Node.js TypeScript JavaScript microservices RPC gRPC event-bus event-driven distributed-tracing workflow orchestration background-jobs cron mTLS service-mesh service-discovery distributed-systems zero-sidecar Istio-alternative RabbitMQ-alternative Temporal-alternative Jaeger-alternative PostgreSQL Docker Kubernetes DLQ dead-letter-queue saga distributed-transactions AI-agent-orchestration Express Fastify HTTP-middleware observability Prometheus tracing service-catalog async-messaging durable-events retries idempotency auto-mTLS runtime-dashboard production-ready bun deno -->
+<!--
+Keywords: service-bridge, ServiceBridge, microservices, Node.js SDK, TypeScript SDK, Bun,
+gRPC, mTLS, RPC framework, durable events, pub/sub, message broker alternative, RabbitMQ alternative,
+workflow engine, saga, orchestration, Temporal alternative, job scheduler, cron, distributed tracing,
+observability, OpenTelemetry alternative, Jaeger alternative, service mesh alternative, Istio alternative,
+self-hosted, PostgreSQL, Express, Fastify, Hono, circuit breaker, idempotency, retries, load balancing.
+-->
 
 # service-bridge
 
-[![npm version](https://img.shields.io/npm/v/service-bridge?color=cb3837&logo=npm)](https://www.npmjs.com/package/service-bridge)
-[![License](https://img.shields.io/badge/License-Free%20%2F%20Commercial-blue)](../LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5%2B-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![Node](https://img.shields.io/badge/Node.js-18%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![npm version](https://img.shields.io/npm/v/service-bridge?color=cb3837&label=npm)](https://www.npmjs.com/package/service-bridge)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/types-included-3178c6.svg)](https://www.typescriptlang.org/)
+[![Node](https://img.shields.io/badge/node-%E2%89%A518-339933.svg)](https://nodejs.org/)
 
-**The Unified Bridge for Microservices Interaction**
+**The Node.js / Bun SDK for [ServiceBridge](https://servicebridge.dev) — RPC, durable events, workflows, jobs, streaming and full observability over one self-hosted runtime. No broker. No sidecar. No tracing stack. Just one Go binary plus PostgreSQL.**
 
-Node.js SDK for [ServiceBridge](https://servicebridge.dev) — production-ready RPC, durable events, workflows, jobs, and distributed tracing in a single SDK. One Go runtime and PostgreSQL.
+You declare what your service handles and what it calls. ServiceBridge does the rest: provisions an mTLS identity, opens the connection, registers your handlers, and routes every RPC, event, job and workflow step — with tracing, metrics and access policy built in.
 
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│                    BEFORE: 10 moving parts                      │
-│  Istio · Envoy · RabbitMQ · Temporal · Jaeger · Consul ·       │
-│  cert-manager · Alertmanager · cron · custom glue              │
-└─────────────────────────────────────────────────────────────────┘
-                              ↓
-┌─────────────────────────────────────────────────────────────────┐
-│               AFTER: ServiceBridge + PostgreSQL                 │
-│  RPC · Events · Workflows · Jobs · Tracing · mTLS · Dashboard  │
-│            One SDK  ·  One runtime  ·  Zero sidecars            │
-└─────────────────────────────────────────────────────────────────┘
+        BEFORE                                       AFTER
+
+  ┌─────────────────────┐
+  │  Istio + Envoy      │  ← mesh / mTLS
+  │  RabbitMQ / Kafka   │  ← events                 ┌──────────────────────┐
+  │  Temporal           │  ← workflows              │                      │
+  │  a cron scheduler   │  ← jobs                   │   ServiceBridge      │
+  │  gRPC plumbing      │  ← RPC          ═══►       │   runtime (1 binary) │
+  │  Jaeger / Tempo     │  ← tracing                │          +           │
+  │  Prometheus wiring  │  ← metrics                │      PostgreSQL      │
+  │  Loki               │  ← logs                   │                      │
+  │  a load balancer    │  ← LB / retries           └──────────────────────┘
+  │  service registry   │  ← discovery
+  └─────────────────────┘
+     10+ moving parts                                  2 things to run
 ```
 
-## Table of Contents
+---
+
+## Table of contents
 
-- [Why ServiceBridge](#why-servicebridge)
-- [Use Cases](#use-cases)
-- [Quick Start](#quick-start)
 - [Install](#install)
-- [Runtime Setup](#runtime-setup)
-- [End-to-End Example](#end-to-end-example)
-- [Platform Features](#platform-features)
-- [How It Compares](#how-it-compares)
-- [API Reference](#api-reference)
-- [HTTP Plugins](#http-plugins)
+- [Why ServiceBridge](#why-servicebridge)
+- [Use cases](#use-cases)
+- [Quick start](#quick-start)
+- [Runtime setup](#runtime-setup)
+- [End-to-end example](#end-to-end-example)
+- [Platform features](#platform-features)
+- [How it compares](#how-it-compares)
+- [API reference](#api-reference)
+  - [RPC](#rpc)
+  - [Events](#events)
+  - [Jobs](#jobs)
+  - [Workflows](#workflows)
+  - [Streaming](#streaming)
+  - [Telemetry](#telemetry)
+  - [HTTP](#http)
+- [HTTP plugins](#http-plugins)
 - [Configuration](#configuration)
-- [Environment Variables](#environment-variables)
-- [Error Handling](#error-handling)
-- [When to Use / When Not to Use](#when-to-use--when-not-to-use)
+- [Error handling](#error-handling)
 - [FAQ](#faq)
-- [Community and Support](#community-and-support)
+- [Community](#community)
 - [License](#license)
 
 ---
 
-## Why ServiceBridge
-
-| Problem | Without ServiceBridge | With ServiceBridge |
-|---|---|---|
-| Service-to-service calls | Istio/Envoy sidecar proxy per pod | **Direct SDK-to-worker gRPC, zero proxy hops** |
-| Async messaging | Kafka/RabbitMQ + retry logic + DLQ setup | **Built-in durable events with retry, DLQ, replay** |
-| Background jobs | Bull/BullMQ + Redis + cron daemon | **Built-in cron and delayed jobs** |
-| Workflow orchestration | Temporal/Conductor cluster + persistence | **Built-in DAG workflows** |
-| Distributed tracing | Jaeger/Tempo + OTEL collector + dashboards | **Built-in traces + realtime UI** |
-| Service discovery | Consul/etcd + DNS glue | **Built-in registry + health-aware balancing** |
-| mTLS | cert-manager + Vault PKI | **Auto-provisioned certs from service key** |
-
-**Result**: `10 tools → 1 runtime`. One Go binary + PostgreSQL replaces the entire stack.
-
----
-
-## Use Cases
-
-**Microservice communication** — Replace sidecar mesh with direct RPC calls. Get sub-millisecond overhead instead of double proxy hop latency.
-
-**Event-driven architecture** — Publish durable events with fan-out, retries, DLQ, idempotency, and server-side filtering. No broker infrastructure to manage.
-
-**Background job scheduling** — Cron jobs, delayed execution, and job-triggered workflows in a single API. No Redis, no separate queue workers.
-
-**Saga / distributed transactions** — DAG workflows with typed steps (`rpc`, `event`, `event_wait`, `sleep`, child workflow). Compensations and rollbacks via workflow step dependencies.
-
-**AI agent orchestration** — Stream LLM tokens via realtime trace streams with replay. Orchestrate multi-step AI pipelines as workflows.
-
-**Full-stack observability** — Every RPC call, event delivery, workflow step, and HTTP request traced automatically. One timeline, one dashboard. Prometheus metrics and Loki-compatible log API included.
-
----
-
-## Quick Start
-
-### 1. Install
+## Install
 
-```bash
+```sh
 npm i service-bridge
 # or
 bun add service-bridge
 ```
 
-### 2. Create a worker (service that handles calls)
+- **Runtime:** Node.js 18+ or any current Bun.
+- **Types:** included, written in TypeScript 5.
+- **Backend:** a running ServiceBridge runtime (gRPC control plane on `:14445`) backed by PostgreSQL 18+. See [Runtime setup](#runtime-setup).
 
 ```ts
 import { ServiceBridge } from "service-bridge";
 
 const sb = new ServiceBridge(
-  process.env.SERVICEBRIDGE_URL ?? "localhost:14445",
-  process.env.SERVICEBRIDGE_SERVICE_KEY!,
+  "localhost:14445", // runtime control-plane address
+  "sb_key_...",      // bootstrap service key from the runtime
 );
-
-sb.rpc.handle("payment.charge", async (payload: { orderId: string; amount: number }) => {
-  return { ok: true, txId: `tx_${Date.now()}`, orderId: payload.orderId };
-});
-
-await sb.start({ host: "localhost" });
 ```
 
-### 3. Call it from another service
-
-```ts
-import { ServiceBridge } from "service-bridge";
+The third constructor argument is an [options](#configuration) object. The SDK reads **no environment variables** — every knob is a constructor option, so you stay in control of where config comes from.
 
-const sb = new ServiceBridge(
-  process.env.SERVICEBRIDGE_URL ?? "localhost:14445",
-  process.env.SERVICEBRIDGE_SERVICE_KEY!,
-);
+### Using an AI coding agent?
 
-const result = await sb.rpc.invoke<{ ok: boolean; txId: string }>("payment.charge", {
-  orderId: "ord_42",
-  amount: 4990,
-});
+Drop in the official **`servicebridge-node`** skill and your agent (Claude Code, etc.) writes correct ServiceBridge code on the first try — RPC, events, workflows, jobs and HTTP integration, grounded in this exact SDK:
 
-console.log(result.txId); // tx_1711234567890
+```sh
+npx degit service-bridge/sdk/skills/servicebridge-node .claude/skills/servicebridge-node
 ```
 
-That's it. No broker, no sidecar, no proxy — direct gRPC call between services.
+Source and details: [`skills/servicebridge-node/`](https://github.com/service-bridge/sdk/tree/main/skills/servicebridge-node).
 
 ---
 
-## Runtime Setup
-
-The SDK connects to a ServiceBridge runtime. The fastest way to start:
-
-```bash
-bash <(curl -fsSL https://servicebridge.dev/install.sh)
-```
-
-This installs ServiceBridge + PostgreSQL via Docker Compose and generates an admin password automatically. After install, the dashboard is at `http://localhost:14444` and the gRPC control plane at `localhost:14445`.
-
-For manual Docker Compose setup, configuration reference, and all runtime environment variables, see the **[Runtime Setup](../README.md#runtime-setup)** section in the main SDK README.
-
----
-
-## End-to-End Example
-
-A complete order flow: HTTP request → RPC → Event → Event handler with streaming.
-
-```ts
-import { ServiceBridge } from "service-bridge";
-
-// --- Payments service (worker) ---
-
-const payments = new ServiceBridge("localhost:14445", process.env.SERVICEBRIDGE_SERVICE_KEY!);
-
-payments.rpc.handle("payment.charge", async (payload: { orderId: string; amount: number }, ctx) => {
-  await ctx?.stream.write({ status: "charging", orderId: payload.orderId }, "progress");
-
-  // ... charge logic ...
-
-  await ctx?.stream.write({ status: "charged" }, "progress");
-  return { ok: true, txId: `tx_${Date.now()}` };
-});
-
-await payments.start({ host: "localhost" });
-```
-
-```ts
-// --- Orders service (caller + event publisher) ---
-
-const orders = new ServiceBridge("localhost:14445", process.env.SERVICEBRIDGE_SERVICE_KEY!);
-
-// Call payments, then publish event
-const charge = await orders.rpc.invoke<{ ok: boolean; txId: string }>("payment.charge", {
-  orderId: "ord_42",
-  amount: 4990,
-});
-
-await orders.events.publish("orders.completed", {
-  orderId: "ord_42",
-  txId: charge.txId,
-}, {
-  idempotencyKey: "order:ord_42:completed",
-  headers: { source: "checkout" },
-});
-```
-
-```ts
-// --- Notifications service (event consumer) ---
+## Why ServiceBridge
 
-const notifications = new ServiceBridge("localhost:14445", process.env.SERVICEBRIDGE_SERVICE_KEY!);
+Microservices rarely fail because of business logic. They fail in the gaps *between* services — the broker that dropped a message, the workflow engine nobody fully understands, the trace that stops at a service boundary, the mesh config that takes a week to debug. Each gap is another system to run, secure and correlate.
 
-notifications.events.handle("orders.*", async (payload, ctx) => {
-  const body = payload as { orderId: string; txId: string };
-  await ctx.stream.write({ status: "sending_email", orderId: body.orderId }, "progress");
-  // ... send email ...
-});
+ServiceBridge collapses those gaps into one runtime. Your service talks to a single gRPC endpoint over mTLS; the runtime is the single source of truth for routing, delivery and state.
 
-await notifications.start({ host: "localhost" });
-```
-
-```ts
-// --- Orchestrate as a workflow ---
-
-await orders.workflows.run("order.fulfillment", [
-  { id: "reserve", type: "rpc", service: "inventory", ref: "inventory.reserve" },
-  { id: "charge", type: "rpc", service: "payment", ref: "payment.charge", deps: ["reserve"] },
-  { id: "wait_dlv", type: "event_wait", ref: "shipping.delivered", deps: ["charge"] },
-  { id: "notify", type: "event", ref: "orders.fulfilled", deps: ["wait_dlv"] },
-]);
-```
+| Problem | Without ServiceBridge | With ServiceBridge |
+|---|---|---|
+| Service-to-service calls | gRPC/HTTP plumbing + a mesh for mTLS + retries | `sb.rpc.call("svc", "Method", req)` — mTLS, LB, retries, breakers built in |
+| Reliable async messaging | Stand up and operate a broker | `sb.event.publish(...)` — durable outbox, at-least-once, fan-out, DLQ |
+| Multi-step business processes | A separate workflow engine to learn and host | `sb.workflow.handle(...)` — durable DAGs with compensation and replay |
+| Scheduled work | A cron box or a job scheduler service | `sb.job.handle(...)` — cron / interval / delay, leased and retried |
+| Knowing what happened | Wire up tracing + metrics + logs across N tools | Every hop is traced, measured and logged automatically |
+| Identity & access | Certificates, a mesh policy layer | mTLS from a service key + granular access policy, on by default |
 
-Every step above — RPC, event publish, event delivery, workflow execution — appears in a single trace timeline in the built-in dashboard.
+One binary, one database, one place to look when something breaks.
 
 ---
 
-## Platform Features
-
-### Communication
-- **Direct RPC** — zero-hop gRPC calls with retries, deadlines, and mTLS identity
-- **Durable Events** — fan-out delivery, guaranteed delivery (RabbitMQ-style), at-least-once guarantees, retries, DLQ, replay, idempotency. If a consumer is offline, the message waits in the server-side queue and is dispatched the moment the consumer reconnects — no retry budget consumed while waiting.
-- **Realtime Streams** — live chunks with replay for AI/progress/log streaming
-- **Service Discovery** — automatic endpoint resolution and round-robin balancing
-- **HTTP Middleware** — Express and Fastify instrumentation with automatic trace propagation
-
-### Orchestration
-- **Workflows** — DAG steps: `rpc`, `event`, `event_wait`, `sleep`, child workflow
-- **Jobs** — cron, delayed, and workflow-triggered scheduling
-
-### Security
-- **TLS by default** — control plane TLS + worker mTLS with gRPC certificate provisioning
-- **Access Policy** — service-level caller/target restrictions and RBAC
-
-### Observability
-- **Unified Tracing** — single trace timeline across HTTP, RPC, events, workflows, and jobs
-- **Metrics** — Prometheus-compatible `/metrics` endpoint (30+ metric families)
-- **Logs** — structured log ingest with Loki-compatible query API
-- **Alerts** — runtime alerts for delivery failures, errors, and service health
-- **Dashboard** — realtime web UI for traces, events, workflows, jobs, DLQ, service map, and service keys
-
----
+## Use cases
 
-## How It Compares
-
-| Concern | Istio + Envoy | Dapr | Temporal + Kafka | ServiceBridge |
-|---|---|---|---|---|
-| RPC data path | Sidecar proxy hop | Sidecar/daemon hop | N/A | **Direct (proxyless)** |
-| Service discovery | K8s control plane | Sidecar placement | External registry | **Built-in registry** |
-| Durable events + DLQ | External broker | Pub/Sub component | Kafka + consumers | **Built-in** |
-| Workflow orchestration | External engine | External engine | Built-in | **Built-in** |
-| Job scheduling | External cron/queue | External scheduler | External scheduler | **Built-in** |
-| Traces + UI | Jaeger/Tempo + dashboards | OTEL backend + dashboards | Temporal UI | **Built-in** |
-| Logs for Grafana | Loki + Promtail pipeline | Log pipeline | Log pipeline | **Built-in Loki API** |
-| Metrics | App/exporter setup | App/exporter setup | Multiple exporters | **Built-in `/metrics`** |
-| Security model | Mesh PKI + policy | Deployment-dependent mTLS | Mixed | **Service keys + auto mTLS** |
-| Operational footprint | Multi-component mesh | Runtime + sidecars | Workflow + broker + DB | **One binary + PostgreSQL** |
+- **Replace a broker** — durable, at-least-once events with fan-out and a dead-letter queue, without operating Kafka or RabbitMQ.
+- **Run sagas / orchestration** — checkout, onboarding, fulfilment as durable workflows with automatic compensation on failure.
+- **Internal RPC backbone** — typed service-to-service calls with load balancing, retries and circuit breakers, secured by mTLS.
+- **Scheduled & delayed work** — nightly rollups, reminders, periodic syncs as leased, retried jobs.
+- **Streaming responses** — token-by-token LLM output or progress feeds over server-side streaming RPC.
+- **Observability for free** — get a full distributed trace across RPC → event → workflow → job without instrumenting by hand.
 
 ---
 
-## API Reference
-
-### `ServiceBridge` / `ServiceBridgeService` surface
-
-Per-instance API for `new ServiceBridge(...)` (implements `ServiceBridgeService`):
-
-- **Namespaces:** `rpc` (`handle`, `invoke`, `declare`), `events` (`handle`, `publish`, `publishWorker`, `declare`), `jobs` (`run`), `workflows` (`run`, `declare`).
-- **Lifecycle:** `start(opts?)`, `stop()`.
-- **Workflows:** `cancelWorkflow(traceId)`.
-- **HTTP & traces:** `startHttpSpan(opts)`, `registerHttpEndpoint(opts)`, `watchTrace(traceId, opts?)`.
-- **Module helpers (exported from `service-bridge`):** `getTraceContext`, `withTraceContext`, `ServiceBridgeError`, `mapGrpcStatus`, `SB`, `SB_MESSAGES`. (`captureConsole` exists internally for log capture but is not part of the public package exports.)
-
-### Cross-SDK parity notes
-
-ServiceBridge keeps the core API shape consistent across Node.js, Go, and Python:
-constructor, `rpc` / `events` / `jobs` / `workflows` namespaces, streams, `start`/`stop`, and `ServiceBridgeError`.
+## Quick start
 
-Constructor-level defaults for `timeout`, `retries`, and `retryDelay` are available
-across all three SDKs. Parity differences are naming-only (language idioms):
+Schemas are **file-based**: point the SDK at a `.proto` file (it resolves request/response types from the `service` block) or a `.schema.json` with explicit field numbers. There is no inline schema.
 
-- Constructor TLS overrides: `workerTLS`/`caCert` (Node), `WorkerTLS`/`CACert` (Go), `worker_tls`/`ca_cert` (Python)
-- Handler hints: timeout/retryable/concurrency/prefetch are advisory in all SDKs
-- Shared `start()` fields across SDKs: host, max in-flight, instance ID, weight, and per-start TLS override
-
-### `new ServiceBridge(url, serviceKey, opts?)`
-
-```ts
-class ServiceBridge {
-  constructor(url: string, serviceKey: string, opts?: ServiceBridgeOpts);
+```proto
+// payment.proto
+syntax = "proto3";
+message ChargeRequest { string user_id = 1; int64 amount = 2; }
+message ChargeReply   { bool ok = 1; }
+service Payment {
+  rpc Charge(ChargeRequest) returns (ChargeReply);
 }
 ```
 
-Creates an SDK client instance. Service identity is resolved by the runtime from the sbv2 `serviceKey` (key id). Use `new ServiceBridge(...)` as the **public** entry point from the `service-bridge` package (the constructor delegates to the same internal client setup used by the SDK; a lower-level factory exists in source but is **not** exported from the published entry).
-
-`ServiceBridgeOpts`:
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `timeout` | `number` | `30000` | Default hard timeout per `rpc.invoke()` attempt (ms). |
-| `retries` | `number` | `3` | Default retry count for `rpc.invoke()`. |
-| `retryDelay` | `number` | `300` | Base backoff delay (ms) for `rpc.invoke()`. |
-| `discoveryRefreshMs` | `number` | `10000` | Discovery refresh period for endpoint updates. |
-| `queueMaxSize` | `number` | `1000` | Max offline queue size for control-plane writes. |
-| `queueOverflow` | `"drop-oldest" \| "drop-newest" \| "error"` | `"drop-oldest"` | Overflow strategy for offline queue. |
-| `heartbeatIntervalMs` | `number` | `10000` | Base heartbeat period for worker registrations. |
-| `captureLogs` | `boolean` | `true` | Forward `console.*` logs to ServiceBridge. |
-| `strictOutboundDeclarations` | `boolean` | `false` | When `true`, every outbound `rpc.invoke()` must be preceded by `rpc.declare(fn)` for the resolved target. |
-
-### Advanced TLS overrides
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `workerTLS` | `WorkerTLSOpts` | auto | Explicit cert/key/CA for worker mTLS. |
-| `caCert` | `string \| Buffer` | from `serviceKey` | Optional control-plane CA override. By default SDK reads CA from sbv2 service key. |
-
-`WorkerTLSOpts`:
+**Worker** — register the handler. One argument in, one value out.
 
 ```ts
-type WorkerTLSOpts = {
-  caCert?: string | Buffer;
-  cert?: string | Buffer;
-  key?: string | Buffer;
-  serverName?: string;
-}
-```
+import { ServiceBridge } from "service-bridge";
 
----
+const sb = new ServiceBridge("localhost:14445", process.env.PAYMENT_KEY!);
 
-### `rpc.invoke(fn, payload?, opts?)`
+sb.rpc.handle(
+  "Charge",
+  async (req: { userId: string; amount: number }) => {
+    return { ok: req.amount > 0 };
+  },
+  { schema: { protoFile: "./payment.proto" } },
+);
 
-```ts
-invoke<T = unknown>(fn: string, payload?: unknown, opts?: RpcOpts): Promise<T>
+await sb.start();
 ```
 
-Calls a registered RPC handler on another worker. Direct gRPC path, no proxy.
-
-**Function name** — `fn` is a single **global function name** (the same string passed to `rpc.handle` on the callee), e.g. `payment.charge` or `user.get`. It must be unique in the catalog and **must not contain `/`**.
-
-`RpcOpts`:
-
-| Option | Type | Description |
-|---|---|---|
-| `timeout` | `number` | Call timeout in ms. |
-| `retries` | `number` | Retry count override. |
-| `retryDelay` | `number` | Base retry delay override. |
-| `traceId` | `string` | Explicit trace id. |
-| `parentSpanId` | `string` | Explicit parent span id. |
-| `mode` | `"direct" \| "proxy"` | Transport mode. `"direct"` (default) connects directly to the worker. `"proxy"` routes through the control plane when direct connection is unavailable. |
+**Caller** — in another process, build a typed client and call it. `sb.client()` reads the `.proto` once, declares every method in its `service` block as an outgoing dependency, loads the schemas, and returns a typed proxy.
 
 ```ts
-const user = await sb.rpc.invoke<{ id: string; name: string }>("user.get", { id: "u_1" });
-
-const user2 = await sb.rpc.invoke<{ id: string; name: string }>("user.get", { id: "u_1" }, {
-  timeout: 5000,
-  retries: 2,
-});
-```
-
-`rpc.invoke()` is bounded even when a downstream worker is silent:
-each attempt has a hard local timeout, retries are finite (`retries + 1` total attempts),
-and after the final failed attempt the root RPC span is closed with `error`.
-
-Retry delay uses exponential backoff: `retryDelay * 2^(attempt-1)`.
+import { ServiceBridge } from "service-bridge";
 
----
+const sb = new ServiceBridge("localhost:14445", process.env.ORDERS_KEY!);
+const payment = await sb.client("payment-svc", "./payment.proto");
 
-### `rpc.declare(fn)`
+await sb.start();
 
-```ts
-declare(fn: string): void
+const res = await payment.Charge({ userId: "u-1", amount: 100 });
+// res.ok === true
 ```
 
-Declares an outbound RPC dependency for registration metadata. When `strictOutboundDeclarations` is `true`, you must call `rpc.declare(fn)` before `rpc.invoke(fn, ...)` for that function. Does not invoke the remote handler.
+Declare dependencies and build typed clients **before** `start()` — they ride along in the first registration. Calls succeed once `start()` has connected.
 
 ---
 
-### `events.publish(topic, payload?, opts?)`
-
-```ts
-publish(topic: string, payload?: unknown, opts?: EventOpts): Promise<string>
-```
-
-Publishes a durable event. Returns `messageId` when online.
+## Runtime setup
 
-`EventOpts`:
+The SDK needs a running ServiceBridge runtime. Spin one up with the one-line installer:
 
-| Option | Type | Description |
-|---|---|---|
-| `traceId` | `string` | Explicit trace id. |
-| `parentSpanId` | `string` | Explicit parent span id. |
-| `idempotencyKey` | `string` | Idempotency key for dedup-safe publishing. |
-| `headers` | `Record<string, string>` | Custom metadata headers. |
-
-```ts
-await sb.events.publish("orders.created", { orderId: "ord_42" }, {
-  idempotencyKey: "order:ord_42",
-  headers: { source: "checkout" },
-});
+```sh
+bash <(curl -fsSL https://servicebridge.dev/install.sh)
 ```
 
----
-
-### `events.publishWorker(topic, payload?, opts?)`
+It pulls the runtime container, wires it to PostgreSQL 18+, and exposes the gRPC control plane on `:14445` and the dashboard on `:14444`. Open the dashboard, create a service, and copy its **bootstrap service key** — that opaque string is the second argument to `new ServiceBridge(url, key)`.
 
-```ts
-publishWorker(
-  topic: string,
-  payload?: unknown,
-  opts?: { traceId?: string; parentSpanId?: string; headers?: Record<string, string> },
-): Promise<string>
-```
+Each instance authenticates with its key: the SDK calls `Bootstrap.Provision`, receives a short-lived leaf certificate, opens an mTLS gRPC channel and registers. Certificates rotate automatically with overlap (the new session is live before the old one closes), so long-running instances never drop traffic at renewal.
 
-Publishes over the worker session stream (after `start()`). If no worker session is active, the promise is rejected.
+Full self-hosting docs live at **[servicebridge.dev/docs](https://servicebridge.dev/docs)**.
 
 ---
 
-### `events.declare(topic)`
-
-```ts
-declare(topic: string): void
-```
+## End-to-end example
 
-Declares an outbound event dependency for registration metadata (does not publish a message).
-
----
-
-### `jobs.run(service, fn, opts)` / `jobs.run(target, opts)`
+A small order flow: an HTTP request triggers a workflow that charges a payment, then publishes an event another service consumes — all traced as one tree.
 
 ```ts
-run(service: string, fn: string, opts: ScheduleOpts & { via: "rpc" }): Promise<string>
-run(target: string, opts: ScheduleOpts & { via: "event" | "workflow" }): Promise<string>
-```
-
-Registers a scheduled or delayed job. Resolves to the registration key: `"${service}/${fn}"` for the RPC overload, or the `target` string for the `event` / `workflow` overload.
-
-`ScheduleOpts`:
-
-| Option | Type | Description |
-|---|---|---|
-| `cron` | `string` | Cron expression. |
-| `delay` | `number` | Delay in ms before execution. Backed by `int32` in the proto — maximum ~24.8 days (~2,147,483,647 ms). |
-| `timezone` | `string` | Timezone for cron execution. |
-| `misfire` | `"fire_now" \| "skip"` | Misfire policy. |
-| `via` | `"event" \| "rpc" \| "workflow"` | Target type. |
-| `retryPolicyJson` | `string` | Retry policy JSON string. |
+import { ServiceBridge } from "service-bridge";
 
-```ts
-await sb.jobs.run("payments", "billing.collect", {
-  cron: "0 * * * *",
-  timezone: "UTC",
-  via: "rpc",
+const sb = new ServiceBridge("localhost:14445", process.env.ORDERS_KEY!);
+
+// Outgoing dependencies — declared before start().
+sb.service("payment-svc", { rpc: ["Charge"] });
+sb.event.define("order.placed", { protoFile: "./events.proto", input: "OrderPlaced" });
+
+// A durable workflow: charge, then announce. Steps run by dependency level.
+sb.workflow.handle("checkout", {
+  input: { type: "object", properties: { orderId: { type: "string" } } },
+  steps: [
+    { id: "charge", type: "call", service: "payment-svc", method: "Charge",
+      input: "$.input" },
+    { id: "announce", type: "publish", event: "order.placed",
+      input: "$.input", waitFor: ["charge"] },
+  ],
 });
-```
 
----
+sb.on("connected", ({ serviceName }) => console.log(`up as ${serviceName}`));
 
-### `workflows.run(name, steps, opts?)` — register DAG
+await sb.start();
 
-TypeScript (single method; behavior depends on the second argument):
-
-```ts
-run(
-  nameOrService: string,
-  stepsOrName: WorkflowStep[] | string,
-  inputOrOpts?: unknown,
-  opts?: ExecuteWorkflowOpts,
-): Promise<string | ExecuteWorkflowResult>
-```
-
-- **Register:** when `stepsOrName` is `WorkflowStep[]`, `nameOrService` is the workflow name, `inputOrOpts` is optional `WorkflowOpts`, and the promise resolves to that name (`string`).
-- **Execute:** when `stepsOrName` is a `string`, `nameOrService` is the target **service** name, `stepsOrName` is the workflow name, `inputOrOpts` is the optional execution input, and `opts` is optional `ExecuteWorkflowOpts` (see execute section below).
-
-Overload as used when registering:
-
-```ts
-run(name: string, steps: WorkflowStep[], opts?: WorkflowOpts): Promise<string>
+// Kick off a run and wait for the final state.
+const { runId } = await sb.workflow.start("checkout", { orderId: "o-1" });
+const state = await sb.workflow.await(runId);
+console.log("done", state);
 ```
 
-Registers (or updates) a workflow definition as a DAG of typed steps. Returns the workflow name.
-
-`WorkflowStep`:
-
-| Field | Type | Description |
-|---|---|---|
-| `id` | `string` | Unique step identifier in the DAG. |
-| `type` | `"rpc" \| "event" \| "event_wait" \| "sleep" \| "workflow"` | Step execution type. |
-| `service` | `string` | Required for `rpc` and `workflow`: target service that owns the function or child workflow. |
-| `ref` | `string` | Target name: RPC function, event topic, waited topic, or child workflow name (per `type`). |
-| `deps` | `string[]` | Dependencies. Empty/omitted means root step. |
-| `if` | `string` | Optional filter expression (step is skipped if false). |
-| `timeoutMs` | `number` | Optional timeout for `rpc` and `event_wait` steps. |
-| `durationMs` | `number` | Required for `sleep` steps. |
-
-`WorkflowOpts` (third argument when registering a DAG — shape below; the interface is defined in the SDK but **not** re-exported from the main `service-bridge` package entry, so use an inline object in app code):
+The consuming service just subscribes:
 
 ```ts
-interface WorkflowOpts {
-  stateLimitBytes?: number; // default 262144 (256 KB)
-  stepTimeoutMs?: number;   // default 30000 (30 s)
-}
-```
-
-| Field | Type | Default | Description |
-|---|---|---|---|
-| `stateLimitBytes` | `number` | `262144` (256 KB) | Maximum serialized state size in bytes. |
-| `stepTimeoutMs` | `number` | `30000` (30 s) | Default per-step timeout in milliseconds. |
-
-```ts
-await sb.workflows.run("order.fulfillment", [
-  { id: "reserve", type: "rpc", service: "inventory", ref: "inventory.reserve" },
-  { id: "charge", type: "rpc", service: "payment", ref: "payment.charge", deps: ["reserve"] },
-  { id: "wait_5m", type: "sleep", durationMs: 300_000, deps: ["charge"] },
-  { id: "notify", type: "event", ref: "orders.fulfilled", deps: ["wait_5m"] },
-]);
+sb.event.handle("order.placed", async (payload) => {
+  await sendReceipt(payload);
+});
+await sb.start();
 ```
 
-With explicit limits:
-
-```ts
-await sb.workflows.run("checkout.flow", steps, { stepTimeoutMs: 60_000 });
-```
+In the dashboard you see one trace spanning the workflow run, the `Charge` RPC, the `order.placed` publish, and its delivery to the subscriber.
 
 ---
 
-### `workflows.declare(service, name)`
+## Platform features
 
-```ts
-declare(service: string, name: string): void
-```
+| Area | What you get |
+|---|---|
+| **Communication** | Direct RPC, server-side streaming, durable events, service discovery, full-mesh routing, a live service map |
+| **Orchestration** | Workflows (DAG steps with compensation), sub-workflows, jobs (cron / interval / delayed), bidirectional replay |
+| **Reliability** | At-least-once delivery, retries, DLQ, idempotency, fan-out, session resilience, multi-instance failover, circuit breakers |
+| **Traffic control** | Load balancing, rate limiting, per-definition limits, filter expressions, adaptive performance |
+| **Security** | TLS by default, mTLS identity, auto-provisioned certs from a service key, granular access policy |
+| **Observability** | Unified tracing with propagation, Prometheus-compatible metrics, structured logs, smart alerts |
 
-Declares an outbound workflow dependency for registration metadata (does not start an execution).
+Designed to run up to 1000 services against a single runtime.
 
 ---
 
-### `workflows.run(service, name, input?, opts?)` — execute
+## How it compares
 
-This is the same `run` method as above when the second argument is the workflow **name** (`string`), not a step array:
+| You'd otherwise reach for | ServiceBridge gives you |
+|---|---|
+| Istio / Linkerd (mesh, mTLS) | mTLS identity + routing + policy, no sidecars |
+| RabbitMQ / Kafka / NATS | Durable events with outbox, fan-out, retries, DLQ |
+| Temporal / Cadence | Durable workflows with compensation, signals, replay |
+| A cron service / Quartz | Leased, retried scheduled jobs |
+| Jaeger / Tempo + Prometheus + Loki | Tracing, metrics and logs, correlated out of the box |
+| gRPC + a service registry | Typed RPC with discovery, LB and breakers |
 
-```ts
-run(service: string, name: string, input?: unknown, opts?: ExecuteWorkflowOpts): Promise<ExecuteWorkflowResult>
-```
+The point isn't that ServiceBridge beats each tool at its own game — it's that you stop running and correlating ten of them.
 
-Starts a workflow execution on demand. The workflow must be registered first via `workflows.run(name, steps)`.
-An alternative to scheduling via `jobs.run(target, { via: "workflow", ... })` — triggers the execution immediately.
+---
 
-| Parameter | Type | Default | Description |
-|---|---|---|---|
-| `service` / `name` | `string` | required | Target service and workflow name. |
-| `input` | `unknown` | `undefined` | Optional JSON-serializable input payload (serialized as JSON for the runtime). |
+## API reference
 
-Returns `{ traceId }`. Use `traceId` with `watchTrace()` to observe execution in real time.
+The bridge exposes four domains (`sb.rpc`, `sb.event`, `sb.job`, `sb.workflow`) plus `sb.stream()` and `sb.telemetry`. Register handlers and declare dependencies **before** `start()`.
 
-`ExecuteWorkflowOpts` (optional fourth argument):
+### RPC
 
-| Option | Type | Description |
-|---|---|---|
-| `traceId` | `string` | Declared on the exported type for API parity; the current Node implementation does **not** forward this field to the control plane (the gRPC request is built without it). Prefer relying on the returned `traceId`. |
+`sb.rpc` is request/response: register handlers, call other services.
 
 ```ts
-const { traceId } = await sb.workflows.run("users", "user.onboarding", { userId: "u_123" });
-```
-
----
-
-### `cancelWorkflow(traceId)`
+// Unary handler: (req) => res
+sb.rpc.handle<ChargeRequest, ChargeReply>(
+  "Charge",
+  async (req) => ({ ok: req.amount > 0 }),
+  { schema: { protoFile: "./payment.proto" } },
+);
 
-```ts
-cancelWorkflow(traceId: string): Promise<void>
+// Server-side streaming handler: (req) => AsyncIterable<chunk>
+sb.rpc.handleStream<GenRequest, Token>(
+  "Generate",
+  async function* (req) {
+    for (const word of req.prompt.split(" ")) yield { token: word };
+  },
+  { schema: { protoFile: "./gen.proto" } },
+);
 ```
 
-Cancels a running workflow instance.
+Calling — the typed proxy from `sb.client()` (preferred), or the lower-level `sb.rpc.call()`:
 
 ```ts
-await sb.cancelWorkflow("trace_01HQ...XYZ");
-```
-
----
-
-### `rpc.handle(fn, handler, opts?)`
+const res = await payment.Charge({ userId: "u-1", amount: 100 });
 
-```ts
-handle(
-  fn: string,
-  handler: (payload: unknown, ctx?: RpcContext) => unknown | Promise<unknown>,
-  opts?: HandleRpcOpts,
-): ServiceBridgeService
+const res2 = await sb.rpc.call("payment-svc", "Charge",
+  { userId: "u-1", amount: 100 },
+  { timeout: "5s", idempotencyKey: "order-42" },
+);
 ```
 
-Registers an RPC handler. Chainable.
-
-`RpcContext`:
-
-| Field | Type | Description |
-|---|---|---|
-| `traceId` | `string` | Current trace ID. |
-| `spanId` | `string` | Current span ID. |
-| `stream` | `StreamWriter` | Real-time stream writer. |
-
-`HandleRpcOpts`:
+`CallOpts` apply per call, layered over `callDefaults` from the constructor:
 
-| Option | Type | Description |
-|---|---|---|
-| `timeout` | `number` | Advisory timeout hint (currently metadata-level, not hard-enforced by runtime). |
-| `retryable` | `boolean` | Advisory retry hint (currently metadata-level, not a strict policy switch). |
-| `concurrency` | `number` | Advisory concurrency hint (currently not hard-enforced). |
-| `schema` | `RpcSchemaOpts` | Inline protobuf schema for binary encode/decode. |
-| `allowedCallers` | `string[]` | Allow-list of caller service names. |
-
-```ts
-sb.rpc.handle("ai.generate", async (payload: { prompt: string }, ctx) => {
-  await ctx?.stream.write({ token: "Hello" }, "output");
-  await ctx?.stream.write({ token: " world" }, "output");
-  return { text: "Hello world" };
-});
-```
-
-`StreamWriter`:
+| `CallOpts` | Type | Default | Description |
+|---|---|---|---|
+| `timeout` | `string` | `"30s"` | Deadline, e.g. `"500ms"`, `"10s"`, `"2m"`. |
+| `requestId` | `string` | random UUID v4 | Correlation id carried to the callee. |
+| `transport` | `"direct" \| "proxy" \| "auto"` | `"auto"` | `direct` = caller→callee mTLS; `proxy` = via the runtime; `auto` = direct when an endpoint is known. |
+| `idempotencyKey` | `string` | none | Opts into runtime-side dedup; replays within the TTL return the cached response. |
+| `retry` | `Partial<RetryOpts>` | exp. backoff | `{ maxAttempts: 3, baseDelayMs: 200, factor: 2, maxDelayMs: 5000, jitter: 0.3 }`. Set `maxAttempts: 1` to disable. |
 
-| Method | Signature | Description |
-|---|---|---|
-| `write` | `write(data: unknown, key?: string): Promise<void>` | Append a real-time chunk to the trace stream. |
-| `end` | `end(key?: string): Promise<void>` | No-op placeholder for API symmetry (lifecycle managed by runtime). |
+Without an `idempotencyKey`, ambiguous failures (`INTERNAL` / `ABORTED` / `UNKNOWN`) are treated as non-retryable so a non-idempotent call is never silently repeated. Schema-version mismatches are filtered at routing time, so blue-green deploys route `v1→v1` and `v2→v2` automatically.
 
----
+### Events
 
-### `events.handle(pattern, handler, opts?)`
+Durable, at-least-once publish/subscribe. Events hit a local SQLite outbox first, then drain to the runtime, so a publish survives a transient disconnect.
 
 ```ts
-handle(
-  pattern: string,
-  handler: (payload: unknown, ctx: EventContext) => void | Promise<void>,
-  opts?: HandleEventOpts,
-): ServiceBridgeService
-```
-
-Registers an event consumer handler. Chainable.
-
-`HandleEventOpts`:
+// Declare what you publish (same file-based SchemaSpec as RPC).
+sb.event.define("order.placed", { protoFile: "./events.proto", input: "OrderPlaced" });
 
-| Option | Type | Description |
-|---|---|---|
-| `concurrency` | `number` | Advisory concurrency hint (currently not hard-enforced). |
-| `prefetch` | `number` | Advisory prefetch hint (currently not hard-enforced). |
-| `retryPolicyJson` | `string` | Retry policy JSON string. |
-| `filterExpr` | `string` | Server-side filter expression. |
-
-The consumer group name is fixed as `<service-key-id>.<pattern>` (derived from your sbv2 key and the pattern string). Registering a second handler for the same pattern throws a duplicate consumer-group error.
-
-**Delivery guarantee**: once a message is accepted by the runtime, delivery to each consumer group
-is guaranteed. If the consumer is offline, the message waits in the server-side queue and is
-dispatched automatically the moment the service reconnects and registers its handlers — no retry
-budget is consumed while waiting. After `SERVICEBRIDGE_DELIVERY_TTL_DAYS` (default 7) days without
-a consumer, the delivery moves to DLQ with reason `delivery_ttl_exceeded`.
-
-`EventContext` helpers:
-
-- `ctx.traceId` — current trace ID
-- `ctx.spanId` — current span ID
-- `ctx.retry(delayMs?)` — ask for redelivery with optional delay
-- `ctx.reject(reason)` — move to DLQ immediately, bypassing remaining retries
-- `ctx.refs` — metadata (`topic`, `groupName`, `messageId`, `attempt`, `headers`)
-- `ctx.stream.write(...)` — append real-time chunks to trace stream
-
-```ts
-sb.events.handle("orders.*", async (payload, ctx) => {
-  const body = payload as { orderId?: string };
-  if (!body.orderId) {
-    ctx.reject("missing_order_id");
-    return;
-  }
-  await ctx.stream.write({ status: "processing", orderId: body.orderId }, "progress");
+// Subscribe — exact name or wildcard ("order.*", "order.#").
+sb.event.handle("order.placed", async (payload) => {
+  await fulfil(payload);
 });
-```
 
----
-
-### `start(opts?)`
+await sb.start();
 
-```ts
-start(opts?: StartOpts): Promise<void>
+const { eventId } = await sb.event.publish("order.placed", { orderId: "o-1", total: 4200 });
 ```
 
-Starts the worker gRPC server and registers handlers with the control plane.
-The promise resolves once startup/registration is complete (it does not block
-the Node.js process). Throws immediately if no handlers are registered (neither `rpc.handle()` nor `events.handle()` have been called).
+Event names must match `^[a-z0-9_-]+(\.[a-z0-9_-]+)*$` (invalid → `InvalidEventNameError`). A full outbox throws `OutboxFullError`.
 
-`StartOpts`:
-
-| Option | Type | Description |
+| `PublishOpts` | Type | Description |
 |---|---|---|
-| `host` | `string` | Bind host. Default: `localhost`. Use `0.0.0.0` in Docker/Kubernetes so ServiceBridge can reach the worker. |
-| `maxInFlight` | `number` | Max in-flight runtime-originated commands over `OpenWorkerSession`. Default: `128`. |
-| `instanceId` | `string` | Stable worker instance identifier. |
-| `weight` | `number` | Scheduling/discovery weight hint. |
-| `tls` | `WorkerTLSOpts` | Per-start worker TLS override. |
-
-```ts
-await sb.start({
-  host: "localhost",
-  instanceId: process.env.HOSTNAME,
-});
-```
-
----
-
-### `stop()`
-
-```ts
-stop(): void
-```
+| `idempotencyKey` | `string` | Dedup key for at-least-once delivery. |
+| `partitionKey` | `string` | Orders delivery within a partition. |
+| `fireAndForget` | `boolean` | Skip the durable wait for the publish ack. |
+| `headers` | `Record<string, string>` | Custom envelope headers. |
+| `occurredAtMs` | `number` | Event time (unix-ms); defaults to now. |
 
-Gracefully stops the worker gRPC server (try graceful shutdown, then force), heartbeats, channels, and SDK internals.
+The runtime delivers at-least-once, retries failures, fans out to every matching subscriber, and dead-letters exhausted messages. The DLQ is operated from the dashboard — the SDK has no DLQ API; make handlers idempotent and throw to signal "retry me".
 
----
+### Jobs
 
-### `startHttpSpan(opts)`
+Scheduled work: cron, fixed interval, or one-shot delay. The runtime owns the schedule, leasing and retries.
 
 ```ts
-startHttpSpan(opts: {
-  method: string;
-  path: string;
-  traceId?: string;
-  parentSpanId?: string;
-}): HttpSpan
-```
-
-Manual HTTP tracing primitive.
-
-```ts
-const span = sb.startHttpSpan({ method: "GET", path: "/health" });
-try {
-  span.end({ statusCode: 200, success: true });
-} catch (e) {
-  span.end({ success: false, error: String(e) });
-}
-```
-
----
+sb.job.handle("nightly-rollup",
+  { trigger: { cron: "0 3 * * *", tz: "UTC" } },     // 5-field cron, no seconds
+  async (ctx) => { await rollup(ctx.scheduledAt); },
+);
 
-### `registerHttpEndpoint(opts)`
+sb.job.handle("heartbeat", { trigger: { interval: 30_000 } }, async () => { await ping(); });
 
-```ts
-registerHttpEndpoint(opts: {
-  method: string;
-  route: string;
-  instanceId?: string;
-  endpoint?: string;
-  allowedCallers?: string[];
-  requestSchemaJson?: string;
-  responseSchemaJson?: string;
-  transport?: string;
-}): Promise<void>
+sb.job.handle("send-reminder",
+  { trigger: { delayed: { at: Date.now() + 60_000 } } }, // Date | number | ISO string
+  async (ctx) => { await remind(ctx.idempotencyKey); },
+);
 ```
 
-Registers HTTP route metadata in the ServiceBridge service catalog (stored and sent on the next Reconcile). **Requires a completed worker `start()`**: until `start()` has finished successfully, the call resolves but does not record the route (HTTP middleware may invoke `registerHttpEndpoint` on first request; catalog entries appear only after `start()` has run).
-
-| Option | Type | Description |
-|---|---|---|
-| `method` | `string` | HTTP method: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, etc. |
-| `route` | `string` | Route pattern with parameter placeholders, e.g. `"/users/:id"`. |
-| `instanceId` | `string` | Present on the public opts type; **not** applied by the current Node client when building `http_routes` for Reconcile (worker identity comes from `start()`). |
-| `endpoint` | `string` | Same as above — use `start()` / deployment wiring for the reachable worker base URL. |
-| `allowedCallers` | `string[]` | Service names allowed to call (RBAC). |
-| `requestSchemaJson` | `string` | JSON schema for request validation metadata. |
-| `responseSchemaJson` | `string` | JSON schema for response validation metadata. |
-| `transport` | `string` | Present on the public opts type; **not** sent per route in the current Node reconcile payload. |
+The handler receives a `JobHandlerCtx`: `{ jobName, executionId, scheduledAt, localScheduledAt, attempt, idempotencyKey, signal }`.
 
-```ts
-await sb.registerHttpEndpoint({
-  method: "GET",
-  route: "/users/:id",
-  requestSchemaJson: '{"type":"object"}',
-  transport: "http",
+| `JobOpts` | Type | Default | Description |
+|---|---|---|---|
+| `trigger` | `{cron, tz?} \| {delayed:{at}} \| {interval}` | required | Exactly one trigger; `interval` is in ms. |
+| `catchup` | `"skip" \| "fire_once" \| "fire_all"` | `skip` | What to do for fire times missed during downtime. |
+| `overlap` | `"skip" \| "allow" \| "buffer_one"` | `allow` | Behaviour when a previous run is still in flight. |
+| `deps` | `DeclaredDep[]` | none | Outgoing deps: `{ rpc }`, `{ event }`, `{ workflow }`. |
+| `maxAttempts` / `leaseTtlMs` / `maxConcurrent` / `retry` | — | runtime default | Execution limits and `{ initialMs, maxMs, multiplier, jitter }` retry. |
+
+### Workflows
+
+Durable DAGs. Declare the graph once; the runtime executes it, persists state between steps, survives restarts, and compensates on failure or cancel.
+
+```ts
+sb.workflow.handle("checkout", {
+  input: { type: "object", properties: { orderId: { type: "string" } } },
+  steps: [
+    { id: "reserve", type: "call", service: "inventory-svc", method: "Reserve",
+      input: "$.input",
+      compensate: { service: "inventory-svc", method: "Release", input: "$.reserve" } },
+    { id: "charge", type: "call", service: "payment-svc", method: "Charge",
+      input: "$.input", waitFor: ["reserve"] },
+    { id: "notify", type: "publish", event: "order.placed",
+      input: "$.input", waitFor: ["charge"] },
+  ],
 });
 ```
 
----
+Top-level steps run in parallel by default; `waitFor` declares dependencies and defines the execution levels. Step types: `call`, `publish`, `sleep`, `wait_event`, `wait_signal`, `workflow` (sub-workflow), `parallel`, `sequence`, `local`. Inputs are JSON-path expressions (`"$.input"`, `"$.reserve.id"`) over the accumulated run state.
 
-### `watchTrace(traceId, opts?)`
+Driving a run:
 
 ```ts
-watchTrace(traceId: string, opts?: WatchTraceOpts): AsyncIterable<TraceStreamEvent>
-```
-
-Subscribes to a trace stream with replay and live updates. `traceId` is the stream
-identifier used by `ctx.stream.write(...)`.
-
-`WatchTraceOpts`:
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `key` | `string` | `""` | Stream key filter (`""` = all keys). |
-| `fromSequence` | `number` | `0` | Replay from sequence cursor. |
+const { runId } = await sb.workflow.start("checkout", { orderId: "o-1" });
 
-`TraceStreamEvent`:
+const state = await sb.workflow.await(runId);          // block until terminal
+const snap  = await sb.workflow.query(runId);          // { status, state, steps: [...] }
+await sb.workflow.signal(runId, "approval", { ok: 1 }); // resume a wait_signal step
+await sb.workflow.cancel(runId);                        // compensate in reverse
+const { runId: forked } = await sb.workflow.replay(runId, { fromStepId: "charge" });
+```
 
-| Field | Type | Description |
-|---|---|---|
-| `type` | `"chunk" \| "trace_complete"` | Event kind. |
-| `traceId` | `string` | Trace identifier being watched. |
-| `key` | `string` | Stream lane key. |
-| `sequence` | `number` | Monotonic sequence number. |
-| `data` | `unknown` | JSON-decoded chunk payload. |
-| `traceStatus` | `string \| undefined` | Final status on `trace_complete`. |
+Use `sb.workflow.query()` for the snapshot — there is no `getStatus`. `start()` with no permission throws `WorkflowAccessDeniedError`; an unknown name throws `WorkflowNotFoundError`; signalling/cancelling a finished run throws `WorkflowTerminalError`.
 
-Behavior:
+### Streaming
 
-- Auto-reconnect with exponential backoff (`500ms` → `5000ms`) on retryable stream failures.
-- Deduplicates by `sequence` across reconnects.
-- Enforces strict JSON for `type="chunk"` payloads (non-JSON chunk terminates stream with fatal error).
-- Enforces internal queue limit `256`; overflow is fatal (consumer must drain promptly).
+Server-side streaming is a first-class RPC shape. Register with `sb.rpc.handleStream`, consume with `sb.stream()` (or the typed proxy, which auto-detects `returns (stream T)` methods).
 
 ```ts
-for await (const evt of sb.watchTrace(traceId, { key: "output", fromSequence: 0 })) {
-  if (evt.type === "chunk") {
-    process.stdout.write(String((evt.data as { token?: string }).token ?? ""));
-  }
-  if (evt.type === "trace_complete") break;
+for await (const chunk of sb.stream("gen-svc", "Generate", { prompt: "write a haiku" })) {
+  process.stdout.write(chunk.token);
 }
 ```
 
----
+Breaking the loop (`break`/`return`) tears down the gRPC stream end to end. Streams are single-pick — never retried — by design.
 
-### Trace Utilities
+### Telemetry
 
-#### `getTraceContext()`
+Telemetry flows automatically: every RPC, event, job, workflow step and HTTP request emits an operation span and propagates the trace across hops. Add your own through `sb.telemetry`; anything emitted inside a handler nests under that handler's trace.
 
 ```ts
-getTraceContext(): TraceCtx | undefined
-```
-
-Returns the current async-local trace context.
+import { Channel, UserSubOp } from "service-bridge";
 
-```ts
-import { getTraceContext } from "service-bridge";
-
-const tc = getTraceContext();
-if (tc) {
-  console.log(tc.traceId, tc.spanId);
+const op = sb.telemetry.startOp({
+  channel: Channel.USER, kind: UserSubOp, subject: "reprice-cart", businessKey: cartId,
+});
+try {
+  await reprice(cartId);
+  op.end(/* Status.SUCCESS */);
+} catch (err) {
+  op.end(/* Status.ERROR */, String(err));
+  throw err;
 }
-```
 
-#### `withTraceContext(ctx, fn)`
-
-```ts
-withTraceContext<T>(ctx: TraceCtx, fn: () => T): T
+sb.telemetry.log.info("cart repriced", { cartId, items: 7 }); // also sb.logger
+sb.telemetry.counter("carts_repriced_total").inc();
+sb.telemetry.gauge("queue_depth").set(42);
+sb.telemetry.histogram("reprice_ms", "ms").observe(12.5);
 ```
 
-Runs a function inside an explicit trace context.
+`startOp()` returns a handle whose `.end(status, message?)` closes the span. Anything emitted before `start()` buffers in an in-memory ring and drains once connected.
 
-```ts
-import { withTraceContext } from "service-bridge";
+### HTTP
 
-withTraceContext({ traceId: "trace-1", spanId: "span-1" }, async () => {
-  await sb.events.publish("audit.log", { action: "user.login" });
-});
-```
+ServiceBridge does **not** proxy your business HTTP. You run your own server; the integration discovers your routes, publishes them to the Service Map, and wraps each request in a trace span so HTTP stitches into the same trace as the RPCs and events it triggers. See [HTTP plugins](#http-plugins).
+
+Useful read accessors after `start()`: `sb.identity()` (current session identity or `null`), `sb.serviceMap()` (live registry: visible methods, instances, endpoints), `sb.policyEvaluation()` (the runtime's current access-policy verdict).
 
 ---
 
-## HTTP Plugins
+## HTTP plugins
 
-### Express (`service-bridge/express`)
+Each integration is a subpath import with an optional peer dependency.
 
-```bash
-npm install express
-```
+**Express** — `service-bridge/express`:
 
 ```ts
 import express from "express";
 import { ServiceBridge } from "service-bridge";
-import { servicebridgeMiddleware, registerExpressRoutes } from "service-bridge/express";
+import { attachExpress } from "service-bridge/express";
 
-const sb = new ServiceBridge(process.env.SERVICEBRIDGE_URL!, process.env.SERVICEBRIDGE_SERVICE_KEY!);
 const app = express();
+app.post("/orders", (req, res) => res.json({ ok: true }));
 
-app.use(servicebridgeMiddleware({
-  client: sb,
-  excludePaths: ["/health"],
-  autoRegister: true,
-}));
-
-app.get("/users/:id", async (req, res) => {
-  const user = await req.servicebridge.rpc.invoke("user.get", { id: req.params.id });
-  res.json(user);
-});
-```
-
-#### `servicebridgeMiddleware(options)`
+const sb = new ServiceBridge("localhost:14445", KEY);
+await sb.start();
 
-```ts
-servicebridgeMiddleware(options: {
-  client: ServiceBridgeService;
-  excludePaths?: string[];
-  propagateTraceHeader?: boolean;
-  autoRegister?: boolean;
-}): express.RequestHandler
+app.listen(3000, () => attachExpress(app, sb, { port: 3000 }));
 ```
 
-- Attaches `req.servicebridge`, `req.traceId`, `req.spanId`
-- Starts/ends HTTP span automatically
-- Optionally sets `x-trace-id` response header
-- Optionally auto-registers route pattern in catalog on first hit
-
-#### `registerExpressRoutes(app, client, opts?)`
-
-Eager route catalog registration without waiting for first request.
-
-```ts
-await registerExpressRoutes(app, sb, {
-  endpoint: "http://10.0.0.5:3000",
-  allowedCallers: ["api-gateway"],
-  excludePaths: ["/health"],
-});
-```
-
----
-
-### Fastify (`service-bridge/fastify`)
-
-```bash
-npm install fastify
-```
+**Fastify** — `service-bridge/fastify`:
 
 ```ts
 import Fastify from "fastify";
 import { ServiceBridge } from "service-bridge";
-import { servicebridgePlugin, wrapHandler } from "service-bridge/fastify";
+import { sbFastify } from "service-bridge/fastify";
 
-const sb = new ServiceBridge(process.env.SERVICEBRIDGE_URL!, process.env.SERVICEBRIDGE_SERVICE_KEY!);
 const app = Fastify();
+const sb = new ServiceBridge("localhost:14445", KEY);
 
-await app.register(servicebridgePlugin, {
-  client: sb,
-  excludePaths: ["/health"],
-  autoRegister: true,
-});
+app.post("/orders", async () => ({ ok: true }));
+await app.register(sbFastify, { sb }); // discovers routes + endpoint in onListen
 
-app.get("/users/:id", wrapHandler(async (request, reply) => {
-  const user = await request.servicebridge.rpc.invoke("user.get", {
-    id: (request.params as any).id,
-  });
-  return reply.send(user);
-}));
+await sb.start();
+await app.listen({ port: 3000 });
 ```
 
-#### `servicebridgePlugin(fastify, options)`
+**Hono** — `service-bridge/hono`:
 
 ```ts
-servicebridgePlugin(fastify, {
-  client,
-  excludePaths?,
-  propagateTraceHeader?,
-  autoRegister?,
-  register?: {
-    instanceId?,
-    endpoint?,
-    allowedCallers?,
-    excludePaths?,
-  },
-})
-```
-
-- Decorates `request.servicebridge`, `request.traceId`, `request.spanId`
-- Traces HTTP lifecycle via hooks
-- Auto-registers routes on `onRoute` before traffic
-
-#### `wrapHandler(handler)`
-
-Runs a Fastify handler inside the current trace context so downstream SDK calls inherit the trace.
-
----
-
-### Trace Utilities (HTTP Plugins)
+import { Hono } from "hono";
+import { ServiceBridge } from "service-bridge";
+import { attachHono } from "service-bridge/hono";
 
-#### `extractTraceFromHeaders(headers)`
+const app = new Hono();
+app.post("/orders", (c) => c.json({ ok: true }));
 
-```ts
-import { extractTraceFromHeaders } from "service-bridge/express";
-// or
-import { extractTraceFromHeaders } from "service-bridge/fastify";
+const sb = new ServiceBridge("localhost:14445", KEY);
+await sb.start();
 
-const { traceId, parentSpanId } = extractTraceFromHeaders(req.headers);
+attachHono(app, sb, { port: 3000 }); // Hono doesn't own the socket — pass the port
+Bun.serve({ port: 3000, fetch: app.fetch });
 ```
 
-Extracts trace context from HTTP headers. Supports W3C `traceparent`, `x-trace-id`/`x-span-id` headers, and generates random IDs as fallback. Useful for custom HTTP framework integrations (Hono, Koa, etc.).
+`attachExpress`/`attachHono` take `{ port, host? }`; `sbFastify` reads the bound address itself. Host defaults to the bound socket, falling back to `127.0.0.1`. Attaching before `start()` is safe — the endpoint rides along in the first registration.
 
 ---
 
 ## Configuration
 
-### TLS behavior
-
-- Worker transport is TLS-only.
-- Control plane is TLS-only. Trust source is embedded into sbv2 service key by default.
-- Embedded/explicit CA PEM is validated with strict x509 parsing.
-- If `workerTLS` is not provided, SDK auto-provisions worker certs via gRPC `ProvisionWorkerCertificate`.
-- `workerTLS.cert` and `workerTLS.key` must be provided together.
-- `start({ tls })` overrides global `workerTLS` for a specific worker instance.
+All configuration lives on the `ServiceBridge` constructor — `new ServiceBridge(url, key, options)`. The SDK reads no environment variables; you decide where `url`, `key` and options come from. Every option is optional.
 
-### Offline queue behavior
-
-When the control plane is unavailable, SDK queues write operations (`events.publish`, `jobs.run`, `workflows.run`, telemetry writes).
-
-- Queue size: `queueMaxSize` (default: 1000)
-- Overflow policy: `queueOverflow` (default: `"drop-oldest"`)
-- Return values for queued writes may be empty strings until flushed
-
----
-
-## Environment Variables
-
-The SDK requires values you pass into `new ServiceBridge(...)`. Common setup:
-
-| Variable | Required | Example | Description |
+| Option | Type | Default | Description |
 |---|---|---|---|
-| `SERVICEBRIDGE_URL` | yes | `localhost:14445` | gRPC control plane URL |
-| `SERVICEBRIDGE_SERVICE_KEY` | yes | `sbv2.<id>.<secret>.<ca>` | Service authentication key (sbv2 only) |
-
-```ts
-const sb = new ServiceBridge(
-  process.env.SERVICEBRIDGE_URL ?? "localhost:14445",
-  process.env.SERVICEBRIDGE_SERVICE_KEY!,
-);
-```
-
----
-
-## Error Handling
-
-`ServiceBridgeError` is exported for normalized SDK and runtime errors.
-
-```ts
-import { ServiceBridge, ServiceBridgeError } from "service-bridge";
-
-try {
-  await sb.rpc.invoke("payment.charge", { orderId: "ord_1" });
-} catch (e) {
-  if (e instanceof ServiceBridgeError) {
-    console.error(e.component, e.operation, e.severity, e.retryable, e.code, e.grpcStatus);
-  }
-  throw e;
-}
-```
-
-| Field | Type | Description |
-|---|---|---|
-| `component` | `string` | SDK subsystem (for example, `"rpc"` or `"event"`). |
-| `operation` | `string` | Operation that failed. |
-| `severity` | `"fatal" \| "retriable" \| "ignorable"` | Error classification. |
-| `retryable` | `boolean` | Whether retry is recommended (`true` when `severity === "retriable"`). |
-| `code` | `ServiceBridgeErrorCode` | Stable SDK error id (`SB_*`). |
-| `grpcStatus` | `number \| undefined` | gRPC status code when the error came from gRPC. |
-| `cause` | `unknown` | Original underlying error. |
-
----
-
-## When to Use / When Not to Use
-
-### ServiceBridge is a good fit when you:
-
-- Have **3+ microservices** that need to communicate via RPC, events, or both
-- Want **RPC + events + workflows + jobs** without managing separate infrastructure for each
-- Need **end-to-end tracing** across all communication patterns in one timeline
-- Want to **eliminate sidecar proxies** and reduce operational overhead
-- Need **durable event delivery** with retry, DLQ, and replay without running a broker
-- Are building **AI/LLM pipelines** and need realtime streaming with replay
-
-### Consider alternatives when you:
-
-- Run a **single monolith** with no service decomposition plans
-- Need **ultra-high-throughput event streaming** (100K+ msg/s sustained) — Kafka is purpose-built for this
-- Need a **full API gateway** with rate limiting, auth plugins, and request transformation — use Kong/Envoy Gateway
-- Already have a **mature Istio/Linkerd mesh** and only need traffic management (no events/workflows/jobs)
-- Need **multi-region event replication** — ServiceBridge currently targets single-region deployments
-
----
-
-## v2 Session API
-
-`session_v2.ts` реализует новый Enterprise Session Protocol — Channel-based bidi stream с 8-состоянийным FSM, адаптивным heartbeat и кредитным управлением потоком. Симметричен с Go и Python SDK.
-
-### Жизненный цикл сессии (8 состояний FSM)
-
-```
-connecting → handshaking → ready ↔ active
-                                 ↘ suspended → (reconnect)
-                                 ↘ draining → closed
-                                 ↘ fenced   (permanent)
-```
-
-| Состояние | Описание |
-|-----------|----------|
-| `connecting` | Устанавливается TCP/TLS соединение |
-| `handshaking` | Отправлен Hello, ждём HelloAck |
-| `ready` | HelloAck получен, команды не выполняются |
-| `active` | Есть активные команды |
-| `suspended` | Heartbeat пропущен 2+ раза |
-| `draining` | Инициирован graceful shutdown |
-| `fenced` | Сервер прислал GOAWAY_FENCED — сессия закрыта навсегда |
-| `closed` | Соединение закрыто |
-
-### Быстрый старт
-
-```typescript
-import { V2SessionClient, validateV2Config } from 'service-bridge';
-
-const cfg = {
-  serverAddress: 'localhost:9090',
-  instanceId: 'worker-1',
-  zone: 'us-east-1a',
-  transportMode: 'direct' as const,
-  maxInflight: 64,
-};
-
-validateV2Config(cfg);
-const session = new V2SessionClient(cfg);
-
-// Отправить Hello при подключении
-const hello = session.getHelloFields();
-
-// Обработать HelloAck от сервера
-session.onHelloAck({
-  sessionId: 'sess-abc',
-  resumeToken: 'token-xyz',
-  epoch: 1n,
-  resumed: false,
-  resumeFromSeq: 0n,
-  replayedCommands: 0,
-  reconciledResults: 0,
-  heartbeatIntervalMs: 10_000,
-  heartbeatTimeoutMs: 30_000,
-  initialPermits: 64,
-  maxPermits: 128,
-  effectiveTransportMode: 'direct',
+| `advertise` | `{ host, port } \| false` | `127.0.0.1` on a free port (with a warning) | Inbound RPC server address. Pass `{ host, port }` in containers / k8s; `false` for caller-only instances that never serve RPC. |
+| `callDefaults` | `CallOpts` | `{}` | Default `CallOpts` merged under every `sb.rpc.call()` / `sb.stream()`. |
+| `failOnPolicyViolation` | `boolean` | `false` | When `true`, any policy warning at registration makes `start()` surface a `disconnected` event and stop. Otherwise warnings are logged and emitted as `policy_violation`. |
+| `telemetry` | `boolean` | `true` | Emit ops/logs/metrics to the runtime. `false` fully disables the telemetry transport. |
+| `telemetryRingSize` | `number` | `262144` (256 KiB) | Byte budget for the in-memory ops ring buffer. |
+| `dataDir` | `string` | `"./.servicebridge"` | Directory for the local SQLite event outbox. |
+| `maxOutboxRows` | `number` | `100000` | Outbox rows before `publish` back-pressures with `OutboxFullError`. |
+| `eventsDrainerBatch` | `number` | `50` | Outbox rows drained to the runtime per tick. |
+| `eventsMaxInFlight` | `number` | `32` | Max concurrent inbound events processed by subscribers. |
+| `payloadMaxBytes` | `number` | `65536` | Per-direction cap on captured payload bytes. |
+| `reconnectIntervalMs` | `number` | `3000` | Delay between reconnect attempts. |
+| `reconnectAttempts` | `number` | `3` | Reconnect attempts before giving up. `0` = unlimited. |
+
+```ts
+const sb = new ServiceBridge("localhost:14445", KEY, {
+  advertise: { host: process.env.POD_IP!, port: 50051 },
+  callDefaults: { timeout: "10s" },
+  reconnectAttempts: 0,
+  dataDir: "/var/lib/myservice/sb",
 });
-
-console.log(session.state); // 'ready'
-
-// Входящая команда
-const accepted = session.onCommandReceived(1n, 'cmd-001');
-if (!accepted) {
-  // backpressure — permits = 0
-}
-
-// Команда выполнена
-session.onCommandCompleted(1n, 'cmd-001');
 ```
 
-### Адаптивный heartbeat (EWMA RTT)
-
-```typescript
-import { AdaptiveHeartbeatV2 } from 'service-bridge';
+### Lifecycle
 
-const hb = new AdaptiveHeartbeatV2(10_000, 30_000);
-
-// Получен pong
-hb.onPong(25); // rttMs
-
-// Следующий интервал (адаптируется по EWMA RTT)
-const nextMs = hb.nextIntervalMs();
-
-// Пропуск — ускоряем пинги
-const missCount = hb.onMiss();
-if (missCount >= 2) {
-  // reconnect
-}
-```
-
-Алгоритм: базовый интервал `intervalMs / 3`; при пропусках делится на `2^miss` (min 2s); при стабильном RTT < 50ms удваивается (max 30s).
-
-### Кредитное управление потоком
+```ts
+const sb = new ServiceBridge("localhost:14445", KEY);
 
-```typescript
-import { FlowControlStateV2 } from 'service-bridge';
+sb.service("payment-svc", { rpc: ["Charge"] });               // what you call
+sb.rpc.handle("Ship", shipHandler, { schema: { protoFile: "./ship.proto" } }); // what you serve
 
-const fc = new FlowControlStateV2(64, 1, 128);
+sb.on("connected",      ({ serviceName }) => console.log(`connected as ${serviceName}`));
+sb.on("reconnecting",   ({ attempt, reason }) => console.warn(`reconnecting #${attempt}: ${reason}`));
+sb.on("disconnected",   ({ reason }) => console.error(`disconnected: ${reason}`));
+sb.on("policy_violation", (v) => console.warn(`policy: ${v.declaration} ${v.value} — ${v.reason}`));
 
-if (fc.tryConsume()) {
-  // dispatch command
-}
+await sb.start();
 
-// Команда завершена — вернуть permit
-fc.release(1);
-
-// Сервер прислал FlowControlUpdate
-fc.setWindow(32);
+process.on("SIGTERM", async () => { await sb.stop(); process.exit(0); });
 ```
 
-### Reconnect и resume
-
-`BackoffV2` реализует экспоненциальный backoff с full jitter (base=100ms, max=30s). При переподключении `getHelloFields()` автоматически включает `resumeToken`, `epoch`, `lastReceivedSeq`, `lastSentSeq`, `completedCommandIds` — сервер продолжит сессию с нужной позиции.
-
-```typescript
-import { BackoffV2 } from 'service-bridge';
+---
 
-const backoff = new BackoffV2();
+## Error handling
 
-while (true) {
-  if (backoff.isCircuitOpen()) break; // 10+ сбоев подряд
+Typed errors are exported from the package root, so you can `catch` precisely:
 
-  const delayMs = backoff.next();
-  await new Promise(r => setTimeout(r, delayMs));
+```ts
+import {
+  RpcAccessDeniedError,
+  WorkflowAccessDeniedError,
+  InvalidEventNameError,
+  OutboxFullError,
+  ServiceBridgeError,
+} from "service-bridge";
 
-  try {
-    // reconnect...
-    backoff.reset();
-  } catch {
-    backoff.recordFail();
+try {
+  await payment.Charge({ userId: "u-1", amount: 100 });
+} catch (err) {
+  if (err instanceof RpcAccessDeniedError) {
+    // denied by access policy: { serviceName, methodName, reason }
+  } else if (err instanceof ServiceBridgeError) {
+    // connection / provisioning failure with a typed .code
   }
 }
 ```
 
-### ConfigPush — динамическая конфигурация транспорта
-
-Сервер может в любой момент прислать `ConfigPush` с новыми правилами маршрутизации:
-
-```typescript
-session.onConfigPush({
-  defaultMode: 'direct',
-  serviceOverrides: {
-    'payment-svc': { mode: 'proxy', fallbackPolicy: 'fallback_to_direct' },
-  },
-  functionOverrides: {
-    'payment.charge': { mode: 'proxy', timeoutMs: 5000 },
-  },
-});
-
-// Разрешить транспорт для функции
-const mode = session.resolveTransportMode('payment.charge'); // 'proxy'
-```
-
-### Все события сессии
-
-| Метод | Описание |
-|-------|----------|
-| `getHelloFields()` | Поля для отправки Hello (первый + resume) |
-| `onHelloAck(ack)` | Обработка HelloAck от сервера |
-| `onCommandReceived(seq, id)` | Входящая команда; возвращает `false` при backpressure |
-| `onCommandCompleted(seq, id)` | Команда выполнена; освобождает permit |
-| `onPermitGrant(n)` | Сервер добавил `n` permits |
-| `onFlowControlUpdate(size, reason)` | Сервер изменил размер окна |
-| `onPong(rttMs)` | Получен pong; обновляет EWMA |
-| `onHeartbeatMiss()` | Таймаут pong; возвращает `true` → `suspended` |
-| `onDrain(reason, deadlineMs)` | Инициировать graceful drain |
-| `onGoaway(code, reason)` | GoawaySignal от сервера |
-| `onConfigPush(config)` | Применить новую конфигурацию транспорта |
-| `resolveTransportMode(fnName)` | Получить режим транспорта для функции |
-| `stop()` | Немедленно закрыть сессию |
-
-### Экспортируемые классы и типы
-
-| Символ | Тип | Описание |
-|--------|-----|----------|
-| `V2SessionClient` | class | Главный клиент сессии |
-| `AdaptiveHeartbeatV2` | class | EWMA RTT heartbeat controller |
-| `FlowControlStateV2` | class | Кредитное управление потоком |
-| `BackoffV2` | class | Exponential backoff + circuit |
-| `PositionTrackerV2` | class | Трекер seq/completed IDs |
-| `ConfigPushStateV2` | class | Менеджер динамической конфигурации |
-| `validateV2Config` | function | Валидация конфига; бросает `Error` |
-| `V2Config` | interface | Конфигурация сессии |
-| `SessionStateV2` | type | Союз 8 состояний FSM |
-| `TransportMode` | type | `'direct' \| 'proxy'` |
-| `HelloAckV2` | interface | Данные HelloAck от сервера |
-| `TransportConfigV2` | interface | ConfigPush payload |
-| `ReconcileRequestV2` | interface | Declarative worker registration request |
-| `FunctionDeclarationV2` | interface | Function declaration for Reconcile |
-| `ConsumerGroupDeclarationV2` | interface | Consumer group declaration |
-| `HttpRouteDeclarationV2` | interface | HTTP route declaration |
-| `JobDeclarationV2` | interface | Job declaration |
-| `WorkflowDeclarationV2` | interface | Workflow declaration |
-| `SubscribeRequestV2` | interface | Registry subscribe request |
-| `WorkerEndpointV2` | interface | Worker endpoint info |
-| `IssueCertificateRequestV2` | interface | Certificate request |
-| `IssueCertificateResponseV2` | interface | Certificate response |
-| `CircuitBreakerConfigV2` | interface | Circuit breaker config |
-| `ZoneConfigV2` | interface | Zone-aware config |
-| `ServiceTransportOverride` | interface | Per-service transport override |
-| `FunctionTransportOverride` | interface | Per-function transport override |
-| `ResumeState` | interface | Reconnect resume state |
-
-From the main entry `service-bridge`, types such as `ServiceBridgeOpts`, `RpcOpts`, `EventOpts`, `HandleRpcOpts`, `HandleEventOpts`, `ScheduleOpts`, `StartOpts`, `ExecuteWorkflowOpts`, and `ExecuteWorkflowResult` are available. The DAG shapes **`WorkflowStep` and `WorkflowOpts` are documented above but are not named exports** from that entry — use inline object literals (inference from `workflows.run(...)`) unless your toolchain exposes deep paths. Example:
-
-```ts
-import type {
-  RpcContext,
-  EventContext,
-  StreamWriter,
-  TraceCtx,
-  RetryPolicy,
-  ServiceBridgeErrorSeverity,
-} from "service-bridge";
-```
+| Error | Thrown when |
+|---|---|
+| `RpcAccessDeniedError` | An RPC call is denied by access policy. Also fires a `policy_violation` event. |
+| `WorkflowAccessDeniedError` | A workflow `start()` is denied by access policy. |
+| `WorkflowNotFoundError` | Starting a workflow name the runtime doesn't know. |
+| `WorkflowTerminalError` | Signalling/cancelling a run that already finished. |
+| `InvalidEventNameError` | Publishing/defining an event whose name fails the naming rule. |
+| `OutboxFullError` | The local event outbox is at `maxOutboxRows` (back-pressure). |
+| `ServiceBridgeError` | Connection / provisioning failures; carries a typed `.code` (retryable ones drive auto-reconnect). |
 
 ---
 
 ## FAQ
 
-**How does ServiceBridge handle service failures?**
-RPC calls have configurable retries with exponential backoff and hard per-attempt timeouts, so a silent downstream service cannot keep a call pending forever. Events are durable (PostgreSQL-backed) with at-least-once delivery per consumer group. Failed deliveries are retried according to policy, then moved to DLQ. Workflows track step state and can be resumed.
+**Do I have to use Protobuf?** You point handlers at a `.proto` file or a `.schema.json` with explicit field numbers. Both are file-based; there is no inline schema.
 
-**Is there vendor lock-in?**
-ServiceBridge is self-hosted. The runtime is a single Go binary + PostgreSQL. SDK calls map to standard patterns (RPC, pub/sub, cron) — migrating away means replacing SDK calls with equivalent library calls.
+**Does ServiceBridge proxy my HTTP traffic?** No. You run your own Express / Fastify / Hono server. The integration only discovers your routes for the Service Map and adds trace spans — your HTTP path is untouched.
 
-**How does tracing work without an OTEL collector?**
-The SDK automatically reports trace spans for every RPC call, event publish/delivery, workflow step, and HTTP request. The runtime stores traces in PostgreSQL and serves them via the built-in dashboard and a Loki-compatible API for Grafana integration.
+**How do I scale horizontally?** Run as many SDK instances as you like; the runtime load-balances RPC across live instances and fails over automatically. The runtime itself is a single source of truth backed by PostgreSQL.
 
-**Can I use ServiceBridge alongside existing infrastructure?**
-Yes. You can adopt incrementally — start with RPC between two services, add events later, then workflows. ServiceBridge doesn't require replacing your existing broker or mesh all at once.
+**What happens on a transient disconnect?** Published events sit in the local SQLite outbox and drain when the connection returns. The SDK auto-reconnects (configurable) and rotates certs with overlap so live instances don't drop traffic.
 
-**What happens when the control plane is down?**
-In-flight direct RPC calls continue working (they go service-to-service, not through the control plane). New discovery lookups, event publishes, and telemetry writes are queued in the SDK offline queue and flushed when the control plane recovers.
+**Where do I see traces, metrics and the DLQ?** In the runtime dashboard on `:14444`. Tracing, metrics and the dead-letter queue are operated there.
 
-**What databases does the runtime support?**
-PostgreSQL 16+. The runtime uses PostgreSQL for all persistence: traces, events, workflows, jobs, service registry, and configuration.
+**Node or Bun?** Both. Node 18+ or any current Bun. Bun-native APIs are used where available.
 
 ---
 
-## Community and Support
+## Community
 
-- Website: [servicebridge.dev](https://servicebridge.dev)
-- GitHub: [github.com/service-bridge](https://github.com/service-bridge)
-- SDK monorepo: [README.md](../README.md)
+- **Website & docs:** [servicebridge.dev](https://servicebridge.dev) · [servicebridge.dev/docs](https://servicebridge.dev/docs)
+- **SDK umbrella repo (all languages):** [github.com/service-bridge/sdk](https://github.com/service-bridge/sdk)
+- **Runtime:** [github.com/servicebridge2/runtime](https://github.com/servicebridge2/runtime)
 
----
-
-## License
-
-Free for non-commercial use. Commercial use requires a separate license. See [LICENSE](../LICENSE).
-
-Copyright (c) 2026 Eugene Surkov.
+This is an alpha release (`2.0.0-alpha`). The API is stabilising — issues and feedback are welcome.
 
 ---
 
-## Keywords
+## License
 
-service-bridge · servicebridge · npm install service-bridge · npm i service-bridge · bun add service-bridge · Node.js SDK · TypeScript SDK · JavaScript microservices · RPC · gRPC · event bus · event-driven · distributed tracing · workflow orchestration · background jobs · cron · mTLS · service mesh · service discovery · zero sidecar · Istio alternative · Envoy alternative · RabbitMQ alternative · Temporal alternative · Jaeger alternative · PostgreSQL · Docker · Kubernetes · DLQ · dead letter queue · saga · distributed transactions · AI agent orchestration · Express middleware · Fastify middleware · HTTP middleware · observability · Prometheus · tracing · service catalog · durable events · retries · idempotency · auto mTLS · runtime dashboard · production ready · microservice communication
+Licensed under the **MIT License** — see [LICENSE](./LICENSE). Free for any use, including commercial; you only need to keep the copyright and license notice (attribution to esurkov1 <esurkovv@yandex.ru>).