service-bridge 1.8.3-dev.44 → 1.8.4-dev.45

package/README.md

@@ -203,8 +203,8 @@ await notifications.serve({ host: "localhost" });
 // --- 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: "reserve",  type: "rpc",        service: "inventory", ref: "stock.reserve" },
+  { id: "charge",   type: "rpc",        service: "payments", 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"] },
 ]);
@@ -409,11 +409,24 @@ Registers a scheduled or delayed job.
 | `retryPolicyJson` | `string` | Retry policy JSON string. |
 
 ```ts
-await sb.job("billing.collect", {
+// RPC job: explicit service and function
+await sb.job("billing", "collect", {
   cron: "0 * * * *",
   timezone: "UTC",
   via: "rpc",
 });
+
+// Event job: single target
+await sb.job("user.signup", {
+  cron: "0 0 * * *",
+  via: "event",
+});
+
+// Workflow job: single target
+await sb.job("monthly_report", {
+  cron: "0 0 1 * *",
+  via: "workflow",
+});
 ```
 
 ---
@@ -432,7 +445,8 @@ 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`. For `rpc` — function name in dot notation (e.g. `"payment.charge"`); the runtime resolves the target service from its registry. For `event`/`event_wait` — topic or pattern. For `workflow` — workflow name. Always use dots, never slashes. |
+| `service` | `string` | **Required** for `rpc` and `workflow` steps. Target logical service name (e.g. `"inventory"`, `"payments"`). |
+| `ref` | `string` | Required for `rpc`, `event`, `event_wait`, `workflow`. For `rpc` — the registered function name (e.g. `"stock.reserve"`, `"payment.charge"`). For `event`/`event_wait` — topic or pattern. For `workflow` — child workflow name. Always use dots, never slashes. |
 | `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. |
@@ -454,8 +468,8 @@ interface WorkflowOpts {
 
 ```ts
 await sb.workflow("order.fulfillment", [
-  { id: "reserve", type: "rpc", ref: "inventory.reserve" },
-  { id: "charge", type: "rpc", ref: "payment.charge", deps: ["reserve"] },
+  { id: "reserve", type: "rpc", service: "inventory", ref: "stock.reserve" },
+  { id: "charge", type: "rpc", service: "payments", 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"] },
 ]);
@@ -469,18 +483,19 @@ await sb.workflow("checkout.flow", steps, { stepTimeoutMs: 60_000 });
 
 ---
 
-### `executeWorkflow(name, input?, opts?)`
+### `executeWorkflow(service, name, input?, opts?)`
 
 ```ts
-executeWorkflow(name: string, input?: unknown, opts?: ExecuteWorkflowOpts): Promise<{ traceId: string; groupTraceId: string }>
+executeWorkflow(service: string, name: string, input?: unknown, opts?: ExecuteWorkflowOpts): Promise<{ traceId: string; groupTraceId: string }>
 ```
 
-Starts a workflow execution on demand. The workflow must be registered first via `workflow()`.
+Starts a workflow execution on demand. The workflow must be registered first via `workflow()` on the target service.
 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. |
+| `service` | `string` | required | Logical service that owns the workflow definition (same as the worker identity that called `workflow()`). |
+| `name` | `string` | required | Workflow name. |
 | `input` | `unknown` | `undefined` | Optional JSON-serializable input payload. |
 
 Returns `{ traceId, groupTraceId }`. Use `traceId` with `watchTrace()` to observe execution in real time.
@@ -492,7 +507,7 @@ Returns `{ traceId, groupTraceId }`. Use `traceId` with `watchTrace()` to observ
 | `traceId` | `string` | Override trace ID for this workflow execution. |
 
 ```ts
-const { traceId, groupTraceId } = await sb.executeWorkflow("user.onboarding", { userId: "u_123" });
+const { traceId, groupTraceId } = await sb.executeWorkflow("users", "user.onboarding", { userId: "u_123" });
 ```
 
 ---