service-bridge 1.6.0-dev.33 → 1.8.0-dev.35

package/README.md

@@ -73,7 +73,7 @@ Node.js SDK for [ServiceBridge](https://servicebridge.dev) — production-ready
 
 **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 run streams with replay. Orchestrate multi-step AI pipelines as workflows.
+**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.
 
@@ -236,7 +236,7 @@ Every step above — RPC, event publish, event delivery, workflow execution —
 - **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 runs, events, workflows, jobs, DLQ, service map, and service keys
+- **Dashboard** — realtime web UI for traces, events, workflows, jobs, DLQ, service map, and service keys
 
 ---
 
@@ -262,7 +262,7 @@ Every step above — RPC, event publish, event delivery, workflow execution —
 ### Cross-SDK parity notes
 
 ServiceBridge keeps the core API shape consistent across Node.js, Go, and Python:
-constructor, RPC, events, jobs, workflows, `runWorkflow`, streams, serve/stop, and `ServiceBridgeError`.
+constructor, RPC, events, jobs, workflows, `executeWorkflow`, streams, serve/stop, and `ServiceBridgeError`.
 
 Constructor-level defaults for `timeout`, `retries`, and `retryDelay` are available
 across all three SDKs. Parity differences are naming-only (language idioms):
@@ -326,6 +326,15 @@ rpc<T = unknown>(fn: string, payload?: unknown, opts?: RpcOpts): Promise<T>
 
 Calls a registered RPC handler on another service. Direct gRPC path, no proxy.
 
+**Function name formats** — `fn` accepts two formats:
+
+| Format | Example | When to use |
+|---|---|---|
+| Plain name | `"charge"` | Function name is globally unique across all services. Resolved automatically via service discovery. |
+| Canonical name | `"payments/charge"` | Multiple services expose a function with the same plain name, or you want to be explicit about the target service. |
+
+Both formats are interchangeable when the name is unique globally. Canonical format is recommended in production for clarity and to avoid ambiguity as your service count grows.
+
 `RpcOpts`:
 
 | Option | Type | Description |
@@ -338,6 +347,10 @@ Calls a registered RPC handler on another service. 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
+// plain name — works when "get" is unique across services
+const user = await sb.rpc<{ id: string; name: string }>("get", { id: "u_1" });
+
+// canonical name — explicit service target, always unambiguous
 const user = await sb.rpc<{ id: string; name: string }>("users/get", { id: "u_1" }, {
   timeout: 5000,
   retries: 2,
@@ -378,6 +391,16 @@ await sb.event("orders.created", { orderId: "ord_42" }, {
 
 ---
 
+### `publishEvent(topic, payload?, opts?)`
+
+```ts
+publishEvent(topic: string, payload?: unknown, opts?: PublishEventOpts): Promise<string>
+```
+
+Publishes an event via the established worker session stream. Requires an active worker session — call after `serve()`. Resolves with `messageId` once the server confirms with `publish_ack`. Times out after 30 s if no ack. Use `event()` when not serving (e.g. caller-only services); use `publishEvent()` from within a worker for lower-latency publishing over the existing session.
+
+---
+
 ### `job(target, opts)`
 
 ```ts
@@ -458,44 +481,44 @@ await sb.workflow("checkout.flow", steps, { stepTimeoutMs: 60_000 });
 
 ---
 
-### `runWorkflow(name, input?, opts?)`
+### `executeWorkflow(name, input?, opts?)`
 
 ```ts
-runWorkflow(name: string, input?: unknown, opts?: RunWorkflowOpts): Promise<{ runId: string; traceId: string }>
+executeWorkflow(name: string, input?: unknown, opts?: ExecuteWorkflowOpts): Promise<{ traceId: string; groupTraceId: string }>
 ```
 
-Starts a workflow run on demand. The workflow must be registered first via `workflow()`.
-An alternative to scheduling via `job(target, { via: "workflow" })` — triggers the run immediately.
+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.
 
 | Parameter | Type | Default | Description |
 |---|---|---|---|
 | `name` | `string` | required | Name of a previously registered workflow. |
 | `input` | `unknown` | `undefined` | Optional JSON-serializable input payload. |
 
-Returns `{ runId, traceId }`. Use `traceId` with `watchRun()` to observe execution in real time.
+Returns `{ traceId, groupTraceId }`. Use `traceId` with `watchTrace()` to observe execution in real time.
 
-`RunWorkflowOpts`:
+`ExecuteWorkflowOpts`:
 
 | Option | Type | Description |
 |---|---|---|
-| `traceId` | `string` | Override trace ID for this workflow run. |
+| `traceId` | `string` | Override trace ID for this workflow execution. |
 
 ```ts
-const { runId, traceId } = await sb.runWorkflow("user.onboarding", { userId: "u_123" });
+const { traceId, groupTraceId } = await sb.executeWorkflow("user.onboarding", { userId: "u_123" });
 ```
 
 ---
 
-### `cancelWorkflowRun(runId)`
+### `cancelWorkflow(traceId)`
 
 ```ts
-cancelWorkflowRun(runId: string): Promise<void>
+cancelWorkflow(traceId: string): Promise<void>
 ```
 
 Cancels a running workflow instance.
 
 ```ts
-await sb.cancelWorkflowRun("run_01HQ...XYZ");
+await sb.cancelWorkflow("trace_01HQ...XYZ");
 ```
 
 ---
@@ -542,7 +565,7 @@ sb.handleRpc("ai/generate", async (payload: { prompt: string }, ctx) => {
 
 | Method | Signature | Description |
 |---|---|---|
-| `write` | `write(data: unknown, key?: string): Promise<void>` | Append a real-time chunk to the run stream. |
+| `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). |
 
 ---
@@ -584,7 +607,7 @@ a consumer, the delivery moves to DLQ with reason `delivery_ttl_exceeded`.
 - `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 run stream
+- `ctx.stream.write(...)` — append real-time chunks to trace stream
 
 ```ts
 sb.handleEvent("orders.*", async (payload, ctx) => {
@@ -702,32 +725,32 @@ await sb.registerHttpEndpoint({
 
 ---
 
-### `watchRun(runId, opts?)`
+### `watchTrace(traceId, opts?)`
 
 ```ts
-watchRun(runId: string, opts?: WatchRunOpts): AsyncIterable<RunStreamEvent>
+watchTrace(traceId: string, opts?: WatchTraceOpts): AsyncIterable<TraceStreamEvent>
 ```
 
-Subscribes to a run stream with replay and live updates. `runId` is the stream
-identifier used by `ctx.stream.write(...)` (typically a trace ID).
+Subscribes to a trace stream with replay and live updates. `traceId` is the stream
+identifier used by `ctx.stream.write(...)`.
 
-`WatchRunOpts`:
+`WatchTraceOpts`:
 
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `key` | `string` | `""` | Stream key filter (`""` = all keys). |
 | `fromSequence` | `number` | `0` | Replay from sequence cursor. |
 
-`RunStreamEvent`:
+`TraceStreamEvent`:
 
 | Field | Type | Description |
 |---|---|---|
-| `type` | `"chunk" \| "run_complete"` | Event kind. |
-| `runId` | `string` | Stream/run identifier being watched. |
+| `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. |
-| `runStatus` | `string \| undefined` | Final status on `run_complete`. |
+| `traceStatus` | `string \| undefined` | Final status on `trace_complete`. |
 
 Behavior:
 
@@ -737,11 +760,11 @@ Behavior:
 - Enforces internal queue limit `256`; overflow is fatal (consumer must drain promptly).
 
 ```ts
-for await (const evt of sb.watchRun(runId, { key: "output", fromSequence: 0 })) {
+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 === "run_complete") break;
+  if (evt.type === "trace_complete") break;
 }
 ```
 
@@ -766,18 +789,18 @@ if (tc) {
 }
 ```
 
-#### `runWithTraceContext(ctx, fn)`
+#### `withTraceContext(ctx, fn)`
 
 ```ts
-runWithTraceContext<T>(ctx: { traceId: string; spanId: string }, fn: () => T): T
+withTraceContext<T>(ctx: { traceId: string; spanId: string }, fn: () => T): T
 ```
 
 Runs a function inside an explicit trace context.
 
 ```ts
-import { runWithTraceContext } from "service-bridge";
+import { withTraceContext } from "service-bridge";
 
-runWithTraceContext({ traceId: "trace-1", spanId: "span-1" }, async () => {
+withTraceContext({ traceId: "trace-1", spanId: "span-1" }, async () => {
   await sb.event("audit.log", { action: "user.login" });
 });
 ```

package/dist/express.js

@@ -1,5 +1,5 @@
 // http/src/express.ts
-import { runWithTraceContext } from "service-bridge";
+import { withTraceContext } from "service-bridge";
 
 // http/src/trace.ts
 function parseTraceparent(traceparent) {
@@ -86,7 +86,7 @@ function servicebridgeMiddleware(options) {
     };
     res.on("finish", onFinish);
     res.on("close", onFinish);
-    runWithTraceContext({ traceId: span.traceId, spanId: span.spanId }, () => {
+    withTraceContext({ traceId: span.traceId, spanId: span.spanId }, () => {
       next();
     });
   };

package/dist/fastify.js

@@ -1,5 +1,5 @@
 // http/src/fastify.ts
-import { runWithTraceContext } from "service-bridge";
+import { withTraceContext } from "service-bridge";
 
 // http/src/trace.ts
 function parseTraceparent(traceparent) {
@@ -111,7 +111,7 @@ function wrapHandler(handler) {
     const traceId = request.traceId;
     const spanId = request.spanId;
     if (traceId && spanId) {
-      return runWithTraceContext({ traceId, spanId }, () => handler(request, reply));
+      return withTraceContext({ traceId, spanId }, () => handler(request, reply));
     }
     return handler(request, reply);
   };