service-bridge 1.7.0-dev.50 → 1.7.0-dev.51

package/README.md

@@ -92,31 +92,31 @@ bun add service-bridge
 ### 2. Create a worker (service that handles calls)
 
 ```ts
-import { servicebridge } from "service-bridge";
+import { ServiceBridge } from "service-bridge";
 
-const sb = servicebridge(
+const sb = new ServiceBridge(
   process.env.SERVICEBRIDGE_URL ?? "localhost:14445",
   process.env.SERVICEBRIDGE_SERVICE_KEY!,
 );
 
-sb.handleRpc("charge", async (payload: { orderId: string; amount: number }) => {
+sb.rpc.handle("payment.charge", async (payload: { orderId: string; amount: number }) => {
   return { ok: true, txId: `tx_${Date.now()}`, orderId: payload.orderId };
 });
 
-await sb.serve({ host: "localhost" });
+await sb.start({ host: "localhost" });
 ```
 
 ### 3. Call it from another service
 
 ```ts
-import { servicebridge } from "service-bridge";
+import { ServiceBridge } from "service-bridge";
 
-const sb = servicebridge(
+const sb = new ServiceBridge(
   process.env.SERVICEBRIDGE_URL ?? "localhost:14445",
   process.env.SERVICEBRIDGE_SERVICE_KEY!,
 );
 
-const result = await sb.rpc<{ ok: boolean; txId: string }>("payment.charge", {
+const result = await sb.rpc.invoke<{ ok: boolean; txId: string }>("payment.charge", {
   orderId: "ord_42",
   amount: 4990,
 });
@@ -147,13 +147,13 @@ For manual Docker Compose setup, configuration reference, and all runtime enviro
 A complete order flow: HTTP request → RPC → Event → Event handler with streaming.
 
 ```ts
-import { servicebridge } from "service-bridge";
+import { ServiceBridge } from "service-bridge";
 
 // --- Payments service (worker) ---
 
-const payments = servicebridge("localhost:14445", process.env.SERVICEBRIDGE_SERVICE_KEY!);
+const payments = new ServiceBridge("localhost:14445", process.env.SERVICEBRIDGE_SERVICE_KEY!);
 
-payments.handleRpc("charge", async (payload: { orderId: string; amount: number }, ctx) => {
+payments.rpc.handle("payment.charge", async (payload: { orderId: string; amount: number }, ctx) => {
   await ctx?.stream.write({ status: "charging", orderId: payload.orderId }, "progress");
 
   // ... charge logic ...
@@ -162,21 +162,21 @@ payments.handleRpc("charge", async (payload: { orderId: string; amount: number }
   return { ok: true, txId: `tx_${Date.now()}` };
 });
 
-await payments.serve({ host: "localhost" });
+await payments.start({ host: "localhost" });
 ```
 
 ```ts
 // --- Orders service (caller + event publisher) ---
 
-const orders = servicebridge("localhost:14445", process.env.SERVICEBRIDGE_SERVICE_KEY!);
+const orders = new ServiceBridge("localhost:14445", process.env.SERVICEBRIDGE_SERVICE_KEY!);
 
 // Call payments, then publish event
-const charge = await orders.rpc<{ ok: boolean; txId: string }>("payment.charge", {
+const charge = await orders.rpc.invoke<{ ok: boolean; txId: string }>("payment.charge", {
   orderId: "ord_42",
   amount: 4990,
 });
 
-await orders.event("orders.completed", {
+await orders.events.publish("orders.completed", {
   orderId: "ord_42",
   txId: charge.txId,
 }, {
@@ -188,25 +188,25 @@ await orders.event("orders.completed", {
 ```ts
 // --- Notifications service (event consumer) ---
 
-const notifications = servicebridge("localhost:14445", process.env.SERVICEBRIDGE_SERVICE_KEY!);
+const notifications = new ServiceBridge("localhost:14445", process.env.SERVICEBRIDGE_SERVICE_KEY!);
 
-notifications.handleEvent("orders.*", async (payload, ctx) => {
+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 ...
 });
 
-await notifications.serve({ host: "localhost" });
+await notifications.start({ host: "localhost" });
 ```
 
 ```ts
 // --- Orchestrate as a workflow ---
 
-await orders.workflow("order.fulfillment", [
-  { id: "reserve",  type: "rpc",        ref: "inventory.reserve" },
-  { id: "charge",   type: "rpc",        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"] },
+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"] },
 ]);
 ```
 
@@ -259,44 +259,51 @@ Every step above — RPC, event publish, event delivery, workflow execution —
 
 ## 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, `executeWorkflow`, streams, serve/stop, and `ServiceBridgeError`.
+constructor, `rpc` / `events` / `jobs` / `workflows` namespaces, streams, `start`/`stop`, and `ServiceBridgeError`.
 
 Constructor-level defaults for `timeout`, `retries`, and `retryDelay` are available
 across all three SDKs. Parity differences are naming-only (language idioms):
 
 - 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 `serve()` fields across SDKs: host, max in-flight, instance ID, weight, and per-serve TLS override
+- Shared `start()` fields across SDKs: host, max in-flight, instance ID, weight, and per-start TLS override
 
-### `servicebridge(url, serviceKey, opts?)`
+### `new ServiceBridge(url, serviceKey, opts?)`
 
 ```ts
-function servicebridge(
-  url: string,
-  serviceKey: string,
-  serviceOrOpts?: string | ServiceBridgeOpts,
-  maybeGlobalOpts?: ServiceBridgeOpts,
-): ServiceBridgeService
+class ServiceBridge {
+  constructor(url: string, serviceKey: string, opts?: ServiceBridgeOpts);
+}
 ```
 
-Creates an SDK client instance.
-Service identity is resolved by the runtime from `serviceKey`; passing a third `service` argument is legacy-only.
+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 attempt (ms). |
-| `retries` | `number` | `3` | Default retry count for `rpc()`. |
-| `retryDelay` | `number` | `300` | Base backoff delay (ms) for `rpc()`. |
+| `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
 
@@ -318,15 +325,15 @@ type WorkerTLSOpts = {
 
 ---
 
-### `rpc(fn, payload?, opts?)`
+### `rpc.invoke(fn, payload?, opts?)`
 
 ```ts
-rpc<T = unknown>(fn: string, payload?: unknown, opts?: RpcOpts): Promise<T>
+invoke<T = unknown>(fn: string, payload?: unknown, opts?: RpcOpts): Promise<T>
 ```
 
 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 `handleRpc` on the callee), e.g. `payment.charge` or `user.get`. It must be unique in the catalog and **must not contain `/`**.
+**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`:
 
@@ -340,15 +347,15 @@ Calls a registered RPC handler on another worker. Direct gRPC path, no proxy.
 | `mode` | `"direct" \| "proxy"` | Transport mode. `"direct"` (default) connects directly to the worker. `"proxy"` routes through the control plane when direct connection is unavailable. |
 
 ```ts
-const user = await sb.rpc<{ id: string; name: string }>("user.get", { id: "u_1" });
+const user = await sb.rpc.invoke<{ id: string; name: string }>("user.get", { id: "u_1" });
 
-const user2 = await sb.rpc<{ 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()` is bounded even when a downstream worker is silent:
+`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`.
 
@@ -356,10 +363,20 @@ Retry delay uses exponential backoff: `retryDelay * 2^(attempt-1)`.
 
 ---
 
-### `event(topic, payload?, opts?)`
+### `rpc.declare(fn)`
+
+```ts
+declare(fn: string): void
+```
+
+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.
+
+---
+
+### `events.publish(topic, payload?, opts?)`
 
 ```ts
-event(topic: string, payload?: unknown, opts?: EventOpts): Promise<string>
+publish(topic: string, payload?: unknown, opts?: EventOpts): Promise<string>
 ```
 
 Publishes a durable event. Returns `messageId` when online.
@@ -374,7 +391,7 @@ Publishes a durable event. Returns `messageId` when online.
 | `headers` | `Record<string, string>` | Custom metadata headers. |
 
 ```ts
-await sb.event("orders.created", { orderId: "ord_42" }, {
+await sb.events.publish("orders.created", { orderId: "ord_42" }, {
   idempotencyKey: "order:ord_42",
   headers: { source: "checkout" },
 });
@@ -382,13 +399,38 @@ await sb.event("orders.created", { orderId: "ord_42" }, {
 
 ---
 
-### `job(target, opts)`
+### `events.publishWorker(topic, payload?, opts?)`
+
+```ts
+publishWorker(
+  topic: string,
+  payload?: unknown,
+  opts?: { traceId?: string; parentSpanId?: string; headers?: Record<string, string> },
+): Promise<string>
+```
+
+Publishes over the worker session stream (after `start()`). If no worker session is active, the promise is rejected.
+
+---
+
+### `events.declare(topic)`
+
+```ts
+declare(topic: string): void
+```
+
+Declares an outbound event dependency for registration metadata (does not publish a message).
+
+---
+
+### `jobs.run(service, fn, opts)` / `jobs.run(target, opts)`
 
 ```ts
-job(target: string, opts: ScheduleOpts): Promise<string>
+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.
+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`:
 
@@ -402,7 +444,7 @@ Registers a scheduled or delayed job.
 | `retryPolicyJson` | `string` | Retry policy JSON string. |
 
 ```ts
-await sb.job("billing.collect", {
+await sb.jobs.run("payments", "billing.collect", {
   cron: "0 * * * *",
   timezone: "UTC",
   via: "rpc",
@@ -411,10 +453,26 @@ await sb.job("billing.collect", {
 
 ---
 
-### `workflow(name, steps, opts?)`
+### `workflows.run(name, steps, opts?)` — register DAG
+
+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
-workflow(name: string, steps: WorkflowStep[], opts?: WorkflowOpts): Promise<string>
+run(name: string, steps: WorkflowStep[], opts?: WorkflowOpts): Promise<string>
 ```
 
 Registers (or updates) a workflow definition as a DAG of typed steps. Returns the workflow name.
@@ -425,13 +483,14 @@ Registers (or updates) a workflow definition as a DAG of typed steps. Returns th
 |---|---|---|
 | `id` | `string` | Unique step identifier in the DAG. |
 | `type` | `"rpc" \| "event" \| "event_wait" \| "sleep" \| "workflow"` | Step execution type. |
-| `ref` | `string` | Required for `rpc`, `event`, `event_wait`, `workflow`. |
+| `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`:
+`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):
 
 ```ts
 interface WorkflowOpts {
@@ -446,9 +505,9 @@ interface WorkflowOpts {
 | `stepTimeoutMs` | `number` | `30000` (30 s) | Default per-step timeout in milliseconds. |
 
 ```ts
-await sb.workflow("order.fulfillment", [
-  { id: "reserve", type: "rpc", ref: "inventory.reserve" },
-  { id: "charge", type: "rpc", ref: "payment.charge", deps: ["reserve"] },
+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"] },
 ]);
@@ -457,35 +516,47 @@ await sb.workflow("order.fulfillment", [
 With explicit limits:
 
 ```ts
-await sb.workflow("checkout.flow", steps, { stepTimeoutMs: 60_000 });
+await sb.workflows.run("checkout.flow", steps, { stepTimeoutMs: 60_000 });
+```
+
+---
+
+### `workflows.declare(service, name)`
+
+```ts
+declare(service: string, name: string): void
 ```
 
+Declares an outbound workflow dependency for registration metadata (does not start an execution).
+
 ---
 
-### `executeWorkflow(name, input?, opts?)`
+### `workflows.run(service, name, input?, opts?)` — execute
+
+This is the same `run` method as above when the second argument is the workflow **name** (`string`), not a step array:
 
 ```ts
-executeWorkflow(name: string, input?: unknown, opts?: ExecuteWorkflowOpts): Promise<{ traceId: string; groupTraceId: string }>
+run(service: string, name: string, input?: unknown, opts?: ExecuteWorkflowOpts): Promise<ExecuteWorkflowResult>
 ```
 
-Starts a workflow execution on demand. The workflow must be registered first via `workflow()`.
-An alternative to scheduling via `job(target, { via: "workflow" })` — triggers the execution immediately.
+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 |
 |---|---|---|---|
-| `name` | `string` | required | Name of a previously registered workflow. |
-| `input` | `unknown` | `undefined` | Optional JSON-serializable input payload. |
+| `service` / `name` | `string` | required | Target service and workflow name. |
+| `input` | `unknown` | `undefined` | Optional JSON-serializable input payload (serialized as JSON for the runtime). |
 
-Returns `{ traceId, groupTraceId }`. Use `traceId` with `watchTrace()` to observe execution in real time.
+Returns `{ traceId }`. Use `traceId` with `watchTrace()` to observe execution in real time.
 
-`ExecuteWorkflowOpts`:
+`ExecuteWorkflowOpts` (optional fourth argument):
 
 | Option | Type | Description |
 |---|---|---|
-| `traceId` | `string` | Override trace ID for this workflow execution. |
+| `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`. |
 
 ```ts
-const { traceId, groupTraceId } = await sb.executeWorkflow("user.onboarding", { userId: "u_123" });
+const { traceId } = await sb.workflows.run("users", "user.onboarding", { userId: "u_123" });
 ```
 
 ---
@@ -504,10 +575,10 @@ await sb.cancelWorkflow("trace_01HQ...XYZ");
 
 ---
 
-### `handleRpc(fn, handler, opts?)`
+### `rpc.handle(fn, handler, opts?)`
 
 ```ts
-handleRpc(
+handle(
   fn: string,
   handler: (payload: unknown, ctx?: RpcContext) => unknown | Promise<unknown>,
   opts?: HandleRpcOpts,
@@ -535,7 +606,7 @@ Registers an RPC handler. Chainable.
 | `allowedCallers` | `string[]` | Allow-list of caller service names. |
 
 ```ts
-sb.handleRpc("ai.generate", async (payload: { prompt: string }, ctx) => {
+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" };
@@ -551,10 +622,10 @@ sb.handleRpc("ai.generate", async (payload: { prompt: string }, ctx) => {
 
 ---
 
-### `handleEvent(pattern, handler, opts?)`
+### `events.handle(pattern, handler, opts?)`
 
 ```ts
-handleEvent(
+handle(
   pattern: string,
   handler: (payload: unknown, ctx: EventContext) => void | Promise<void>,
   opts?: HandleEventOpts,
@@ -567,13 +638,12 @@ Registers an event consumer handler. Chainable.
 
 | Option | Type | Description |
 |---|---|---|
-| `groupName` | `string` | Consumer group name. Default: `<service-key-id>.<pattern>`. |
 | `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. |
 
-Duplicate `groupName` registration throws an error.
+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
@@ -591,7 +661,7 @@ a consumer, the delivery moves to DLQ with reason `delivery_ttl_exceeded`.
 - `ctx.stream.write(...)` — append real-time chunks to trace stream
 
 ```ts
-sb.handleEvent("orders.*", async (payload, ctx) => {
+sb.events.handle("orders.*", async (payload, ctx) => {
   const body = payload as { orderId?: string };
   if (!body.orderId) {
     ctx.reject("missing_order_id");
@@ -603,17 +673,17 @@ sb.handleEvent("orders.*", async (payload, ctx) => {
 
 ---
 
-### `serve(opts?)`
+### `start(opts?)`
 
 ```ts
-serve(opts?: ServeOpts): Promise<void>
+start(opts?: StartOpts): Promise<void>
 ```
 
 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 `handleRpc()` nor `handleEvent()` have been called).
+the Node.js process). Throws immediately if no handlers are registered (neither `rpc.handle()` nor `events.handle()` have been called).
 
-`ServeOpts`:
+`StartOpts`:
 
 | Option | Type | Description |
 |---|---|---|
@@ -621,10 +691,10 @@ the Node.js process). Throws immediately if no handlers are registered (neither
 | `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-serve worker TLS override. |
+| `tls` | `WorkerTLSOpts` | Per-start worker TLS override. |
 
 ```ts
-await sb.serve({
+await sb.start({
   host: "localhost",
   instanceId: process.env.HOSTNAME,
 });
@@ -681,19 +751,18 @@ registerHttpEndpoint(opts: {
 }): Promise<void>
 ```
 
-Registers HTTP route metadata in the ServiceBridge service catalog.
-Also starts a periodic heartbeat to keep the HTTP endpoint alive in the registry.
+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` | Stable identifier for this process instance. |
-| `endpoint` | `string` | Reachable address, e.g. `"http://10.0.0.1:3000"`. |
+| `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` | Transport label (e.g. `"http"`, `"https"`). |
+| `transport` | `string` | Present on the public opts type; **not** sent per route in the current Node reconcile payload. |
 
 ```ts
 await sb.registerHttpEndpoint({
@@ -756,7 +825,7 @@ for await (const evt of sb.watchTrace(traceId, { key: "output", fromSequence: 0
 #### `getTraceContext()`
 
 ```ts
-getTraceContext(): { traceId: string; spanId: string } | undefined
+getTraceContext(): TraceCtx | undefined
 ```
 
 Returns the current async-local trace context.
@@ -773,7 +842,7 @@ if (tc) {
 #### `withTraceContext(ctx, fn)`
 
 ```ts
-withTraceContext<T>(ctx: { traceId: string; spanId: string }, fn: () => T): T
+withTraceContext<T>(ctx: TraceCtx, fn: () => T): T
 ```
 
 Runs a function inside an explicit trace context.
@@ -782,7 +851,7 @@ Runs a function inside an explicit trace context.
 import { withTraceContext } from "service-bridge";
 
 withTraceContext({ traceId: "trace-1", spanId: "span-1" }, async () => {
-  await sb.event("audit.log", { action: "user.login" });
+  await sb.events.publish("audit.log", { action: "user.login" });
 });
 ```
 
@@ -798,10 +867,10 @@ npm install express
 
 ```ts
 import express from "express";
-import { servicebridge } from "service-bridge";
+import { ServiceBridge } from "service-bridge";
 import { servicebridgeMiddleware, registerExpressRoutes } from "service-bridge/express";
 
-const sb = servicebridge(process.env.SERVICEBRIDGE_URL!, process.env.SERVICEBRIDGE_SERVICE_KEY!);
+const sb = new ServiceBridge(process.env.SERVICEBRIDGE_URL!, process.env.SERVICEBRIDGE_SERVICE_KEY!);
 const app = express();
 
 app.use(servicebridgeMiddleware({
@@ -811,7 +880,7 @@ app.use(servicebridgeMiddleware({
 }));
 
 app.get("/users/:id", async (req, res) => {
-  const user = await req.servicebridge.rpc("user.get", { id: req.params.id });
+  const user = await req.servicebridge.rpc.invoke("user.get", { id: req.params.id });
   res.json(user);
 });
 ```
@@ -854,10 +923,10 @@ npm install fastify
 
 ```ts
 import Fastify from "fastify";
-import { servicebridge } from "service-bridge";
+import { ServiceBridge } from "service-bridge";
 import { servicebridgePlugin, wrapHandler } from "service-bridge/fastify";
 
-const sb = servicebridge(process.env.SERVICEBRIDGE_URL!, process.env.SERVICEBRIDGE_SERVICE_KEY!);
+const sb = new ServiceBridge(process.env.SERVICEBRIDGE_URL!, process.env.SERVICEBRIDGE_SERVICE_KEY!);
 const app = Fastify();
 
 await app.register(servicebridgePlugin, {
@@ -867,7 +936,7 @@ await app.register(servicebridgePlugin, {
 });
 
 app.get("/users/:id", wrapHandler(async (request, reply) => {
-  const user = await request.servicebridge.rpc("user.get", {
+  const user = await request.servicebridge.rpc.invoke("user.get", {
     id: (request.params as any).id,
   });
   return reply.send(user);
@@ -926,11 +995,11 @@ Extracts trace context from HTTP headers. Supports W3C `traceparent`, `x-trace-i
 - 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.
-- `serve({ tls })` overrides global `workerTLS` for a specific worker instance.
+- `start({ tls })` overrides global `workerTLS` for a specific worker instance.
 
 ### Offline queue behavior
 
-When the control plane is unavailable, SDK queues write operations (`event`, `job`, `workflow`, telemetry writes).
+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"`)
@@ -940,7 +1009,7 @@ When the control plane is unavailable, SDK queues write operations (`event`, `jo
 
 ## Environment Variables
 
-The SDK requires values you pass into `servicebridge(...)`. Common setup:
+The SDK requires values you pass into `new ServiceBridge(...)`. Common setup:
 
 | Variable | Required | Example | Description |
 |---|---|---|---|
@@ -948,7 +1017,7 @@ The SDK requires values you pass into `servicebridge(...)`. Common setup:
 | `SERVICEBRIDGE_SERVICE_KEY` | yes | `sbv2.<id>.<secret>.<ca>` | Service authentication key (sbv2 only) |
 
 ```ts
-const sb = servicebridge(
+const sb = new ServiceBridge(
   process.env.SERVICEBRIDGE_URL ?? "localhost:14445",
   process.env.SERVICEBRIDGE_SERVICE_KEY!,
 );
@@ -961,13 +1030,13 @@ const sb = servicebridge(
 `ServiceBridgeError` is exported for normalized SDK and runtime errors.
 
 ```ts
-import { servicebridge, ServiceBridgeError } from "service-bridge";
+import { ServiceBridge, ServiceBridgeError } from "service-bridge";
 
 try {
-  await sb.rpc("payment.charge", { orderId: "ord_1" });
+  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);
+    console.error(e.component, e.operation, e.severity, e.retryable, e.code, e.grpcStatus);
   }
   throw e;
 }
@@ -978,8 +1047,9 @@ try {
 | `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. |
-| `code` | `number \| undefined` | gRPC status code (if available). |
+| `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. |
 
 ---
@@ -1036,7 +1106,6 @@ import { V2SessionClient, validateV2Config } from 'service-bridge';
 
 const cfg = {
   serverAddress: 'localhost:9090',
-  serviceName: 'my-worker',
   instanceId: 'worker-1',
   zone: 'us-east-1a',
   transportMode: 'direct' as const,
@@ -1210,12 +1279,10 @@ const mode = session.resolveTransportMode('payment.charge'); // 'proxy'
 | `FunctionTransportOverride` | interface | Per-function transport override |
 | `ResumeState` | interface | Reconnect resume state |
 
-Key types available for import:
+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 {
-  WorkflowStep,
-  WorkerTLSOpts,
   RpcContext,
   EventContext,
   StreamWriter,