service-bridge 2.0.0-alpha.1 → 2.0.0-alpha.3

package/README.md

@@ -40,6 +40,7 @@ You declare what your service handles and what it calls. ServiceBridge does the
 ## Table of contents
 
 - [Install](#install)
+- [AI coding skill](#ai-coding-skill)
 - [Why ServiceBridge](#why-servicebridge)
 - [Use cases](#use-cases)
 - [Quick start](#quick-start)
@@ -87,15 +88,25 @@ const sb = new ServiceBridge(
 
 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.
 
-### Using an AI coding agent?
+---
+
+## AI coding skill
+
+This package ships an official skill so your AI coding agent (Claude Code, etc.) writes correct ServiceBridge code on the first try — RPC, events, workflows, jobs and Express/Fastify/Hono integration, grounded in this exact SDK rather than guessed.
+
+It comes with the install. Copy it into your agent's skills directory — `.claude/skills/` for Claude Code, or `~/.claude/skills/` for all projects:
+
+```sh
+cp -r node_modules/service-bridge/skill .claude/skills/servicebridge-node
+```
 
-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:
+Not installed yet? Pull it straight from the repo with degit:
 
 ```sh
-npx degit service-bridge/sdk/skills/servicebridge-node .claude/skills/servicebridge-node
+npx degit service-bridge/sdk/node/skill .claude/skills/servicebridge-node
 ```
 
-Source and details: [`skills/servicebridge-node/`](https://github.com/service-bridge/sdk/tree/main/skills/servicebridge-node).
+Restart the agent so it loads the skill. Source and contents: [`node/skill/`](https://github.com/service-bridge/sdk/tree/main/node/skill).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "service-bridge",
-	"version": "2.0.0-alpha.1",
+	"version": "2.0.0-alpha.3",
 	"description": "TypeScript SDK for ServiceBridge — RPC, durable events, workflows, jobs and observability over a single self-hosted gRPC runtime with mTLS.",
 	"license": "MIT",
 	"type": "module",
@@ -14,7 +14,6 @@
 	},
 	"homepage": "https://servicebridge.dev",
 	"publishConfig": {
-		"tag": "alpha",
 		"access": "public",
 		"provenance": true
 	},
@@ -33,6 +32,7 @@
 	},
 	"files": [
 		"dist",
+		"skill",
 		"README.md",
 		"LICENSE"
 	],

package/skill/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: servicebridge-node
+description: Build backend services with the ServiceBridge Node SDK (service-bridge on npm) — RPC, durable events, workflows, scheduled jobs, and Express/Fastify/Hono integration against a self-hosted ServiceBridge runtime. Use when writing TypeScript/JavaScript that calls or handles RPC, publishes or consumes events, defines workflows or jobs, or wires an HTTP framework into the service mesh.
+---
+
+# ServiceBridge Node SDK
+
+ServiceBridge is a self-hosted runtime ("one container + PostgreSQL") that replaces a service mesh, a message broker, and a workflow engine. Your service declares its handlers and dependencies, then `start()`s — the runtime owns transport, delivery, orchestration, policy, and observability. No sidecars.
+
+This SDK is the **backend** client for that runtime. The npm package is **`service-bridge`** (with a hyphen). Everything in this skill is the real, current API — do not invent methods or options.
+
+## The one mental model that prevents most mistakes
+
+A `ServiceBridge` instance has two phases. Get this wrong and nothing connects.
+
+1. **Before `start()` — declare.** Register incoming handlers (`rpc.handle`, `event.handle`, `workflow.handle`, `job.handle`), declare outgoing dependencies (`service()`, `client()`, `useSchema()`), attach HTTP frameworks. These ride along in the first registration to the runtime.
+2. **`await sb.start()`** — connect, authenticate (mTLS from the bootstrap key), register everything atomically.
+3. **After `start()` — act.** Make outgoing calls: `rpc.call`, `event.publish`, `workflow.start`. These need a live connection.
+
+```ts
+import { ServiceBridge } from "service-bridge";
+
+// 1. construct — url + bootstrap key, nothing else is read from env
+const sb = new ServiceBridge("localhost:14445", process.env.PAYMENT_KEY!);
+
+// 2. declare (before start)
+sb.rpc.handle(
+  "Charge",
+  async (req: { userId: string; amount: number }) => ({ ok: req.amount > 0 }),
+  { schema: { protoFile: "./payment.proto", input: "ChargeRequest", output: "ChargeReply" } },
+);
+
+// 3. connect
+await sb.start();
+
+// 4. act (after start)
+// const res = await sb.rpc.call("other-svc", "Method", { ... });
+
+// teardown
+// await sb.stop();
+```
+
+## Golden rules
+
+- **Package name is `service-bridge`.** `npm i service-bridge` / `import { ServiceBridge } from "service-bridge"`. Never `servicebridge`.
+- **The SDK reads NO env vars for `url`/`key`.** You pass them explicitly (e.g. `process.env.PAYMENT_KEY!`). It only reads `SB_HTTP_ADVERTISE_HOST`/`SB_ADVERTISE_HOST` as a fallback for HTTP-plugin advertise host.
+- **Get the bootstrap key from the dashboard.** Open the runtime dashboard (`http://localhost:14444`) → **Services → Create service** → copy the `sb.…` string. That opaque value is the second constructor arg. (From runtime source you can also mint one with `go run ./cmd/sbkey-gen -name <svc> -dsn <postgres-dsn>`.)
+- **Every RPC handler needs a `schema`.** `rpc.handle(name, fn, { schema })` — schema is required. Without it, registration fails.
+- **`event.handle` matches the EXACT event name**, not a wildcard. Wildcard routing is configured server-side, not in the handler string.
+- **Event and job handlers must be idempotent.** Delivery is at-least-once. For jobs, dedup on `ctx.idempotencyKey`, never on `ctx.attempt`.
+- **Declare before `start()`, call after `start()`.** Outgoing `rpc.call`/`event.publish`/`workflow.start` before `start()` throw "not ready".
+- **Teardown is `await sb.stop()`.** There is no `close()`.
+- **Set `advertise` in production.** If a service handles RPC, pass `{ advertise: { host, port } }` (e.g. the pod IP). Omitting it falls back to `127.0.0.1` (local-only) with a warning. A pure caller can pass `advertise: false`.
+
+## Install & connect
+
+```sh
+npm i service-bridge      # or: bun add service-bridge
+```
+
+The runtime must be running. One-line install of the runtime:
+
+```sh
+bash <(curl -fsSL https://servicebridge.dev/install.sh)
+```
+
+Dashboard at `http://localhost:14444` (create your admin account on first open, then create services to get keys); SDK connects to the gRPC control plane at `localhost:14445`.
+
+## What each domain is for
+
+| You want to… | Use | Reference |
+|---|---|---|
+| Request/response between services (incl. streaming) | `sb.rpc` | [reference/rpc.md](reference/rpc.md) |
+| Fire-and-forget / pub-sub with durable at-least-once delivery | `sb.event` | [reference/events.md](reference/events.md) |
+| Multi-step orchestration (DAG, compensation, signals, replay) | `sb.workflow` | [reference/workflows.md](reference/workflows.md) |
+| Cron / delayed / interval scheduled work | `sb.job` | [reference/jobs.md](reference/jobs.md) |
+| Expose your Express/Fastify/Hono app to Service Map + discovery | `service-bridge/{express,fastify,hono}` | [reference/http-integrations.md](reference/http-integrations.md) |
+| Constructor options, error types, capacity tuning | `ServiceBridgeOptions` | [reference/configuration.md](reference/configuration.md) |
+
+Read the matching reference file before writing code for a domain — each has exact signatures, defaults, and a runnable recipe. When a task spans domains, the lifecycle rule above still holds: one `ServiceBridge` per process, declare everything, then `start()`.
+
+## Minimal two-service RPC (the canonical smoke test)
+
+```ts
+// provider.ts
+import { ServiceBridge } from "service-bridge";
+const sb = new ServiceBridge("localhost:14445", process.env.PROVIDER_KEY!);
+sb.rpc.handle(
+  "Charge",
+  async (req: { userId: string; amount: number }) => ({ transactionId: `tx-${req.userId}`, ok: req.amount > 0 }),
+  { schema: { protoFile: "./payment.proto", input: "ChargeRequest", output: "ChargeReply" } },
+);
+await sb.start();
+```
+
+```ts
+// caller.ts
+import { ServiceBridge } from "service-bridge";
+const sb = new ServiceBridge("localhost:14445", process.env.CALLER_KEY!);
+const payment = await sb.client("payment-svc", "./payment.proto"); // payment-svc = provider's service name
+await sb.start();
+const res = await payment.Charge({ userId: "u-1", amount: 100 }); // { transactionId: "tx-u-1", ok: true }
+```
+
+```proto
+// payment.proto — the shared contract
+syntax = "proto3";
+package demo;
+message ChargeRequest { string user_id = 1; double amount = 2; }
+message ChargeReply   { string transaction_id = 1; bool ok = 2; }
+service Payment { rpc Charge(ChargeRequest) returns (ChargeReply); }
+```
+
+The caller targets the provider by its **service name** (the name used when the service was created in the dashboard), not by host/port — the runtime resolves routing.

package/skill/reference/configuration.md

@@ -0,0 +1,93 @@
+# Configuration, lifecycle & errors
+
+## Constructor
+
+```ts
+new ServiceBridge(url: string, key: string, options?: ServiceBridgeOptions)
+```
+
+- `url` — runtime gRPC control plane, e.g. `"localhost:14445"`.
+- `key` — the `sb.…` bootstrap key (dashboard → Services → Create service, or `sbkey-gen`).
+- The SDK reads **no env vars** for `url`/`key`. Pass them yourself: `new ServiceBridge(process.env.SERVICEBRIDGE_URL!, process.env.MY_SERVICE_KEY!)`.
+
+## ServiceBridgeOptions
+
+```ts
+interface ServiceBridgeOptions {
+  advertise?: { host: string; port: number } | false;  // see below
+  callDefaults?: CallOpts;            // base opts for every rpc.call; default {}
+  failOnPolicyViolation?: boolean;    // default false (warn only)
+  telemetry?: boolean;                // default true
+  telemetryRingSize?: number;         // default 262144 (256 KiB)
+  dataDir?: string;                   // event outbox dir; default "./.servicebridge"
+  maxOutboxRows?: number;             // default 100000 (publish backpressures at cap)
+  eventsDrainerBatch?: number;        // default 50
+  eventsMaxInFlight?: number;         // default 32
+  payloadMaxBytes?: number;           // per-direction capture cap; default 65536
+  reconnectIntervalMs?: number;       // default 3000
+  reconnectAttempts?: number;         // default 3 (0 = unlimited)
+}
+```
+
+### advertise
+
+Controls the inbound Call RPC server (needed if this service **handles** RPC or workflows):
+
+- `{ host, port }` — explicit; use in production (e.g. `{ host: process.env.POD_IP!, port: 7777 }`, `port: 0` lets the OS pick).
+- omitted — binds `127.0.0.1` on a free port and logs a warning (local dev only; not reachable cross-host).
+- `false` — caller-only; bind no inbound server. Use when the instance only makes outgoing calls.
+
+## Lifecycle
+
+```ts
+await sb.start();   // connect, authenticate, register everything declared so far
+await sb.stop();    // graceful shutdown (there is no close())
+```
+
+Declare handlers/dependencies/clients/HTTP plugins **before** `start()`. Make outgoing calls (`rpc.call`, `event.publish`, `workflow.start`) **after** `start()`.
+
+## Declaring dependencies
+
+```ts
+sb.service(serviceName: string, deps: { rpc?: string[]; workflows?: string[]; http?: string[] }): void
+```
+
+Declares what this service calls, so the runtime can wire the graph and enforce policy. `client()` does this for you for RPC; use `service()` for explicit/low-level `rpc.call`.
+
+## Introspection & events
+
+```ts
+sb.identity(): { sessionId; serviceId; serviceName; instanceId } | null   // null until connected
+sb.serviceMap(): ReadonlyMap<string, ServiceMapEntry>                     // live discovery snapshot
+sb.on("connected" | "reconnecting" | "disconnected" | "policy_violation", handler): this
+```
+
+```ts
+sb.on("disconnected", (e) => {
+  console.error("disconnected:", e.reason, e.error?.code); // e.error is a ServiceBridgeError (gRPC code)
+});
+```
+
+## Error types
+
+```ts
+import {
+  ServiceBridgeError,        // base; .code = gRPC status (16 UNAUTHENTICATED, 7 PERMISSION_DENIED, ...)
+  RpcAccessDeniedError,      // rpc.call denied by policy (serviceName, methodName, reason)
+  WorkflowAccessDeniedError, // workflow.start denied by policy
+  WorkflowNotFoundError,     // workflow.start on unknown name
+  WorkflowTerminalError,     // signal/cancel on a terminal run
+  InvalidEventNameError,     // bad event name
+  OutboxFullError,           // event outbox at cap
+} from "service-bridge";
+```
+
+Connection/auth problems arrive via the `disconnected` event carrying a `ServiceBridgeError`. Codes `UNAUTHENTICATED (16)`, `PERMISSION_DENIED (7)`, `NOT_FOUND (5)`, `INVALID_ARGUMENT (3)` are fatal (no reconnect); others trigger reconnect per `reconnectAttempts`/`reconnectIntervalMs`.
+
+## Production checklist
+
+- Set `advertise: { host: <reachable host>, port }` on any service that handles RPC/workflows.
+- Pass `url`/`key` from your own config/secrets; key from the dashboard.
+- Consider `reconnectAttempts: 0` (unlimited) for long-lived services.
+- Make event and job handlers idempotent.
+- Tune `maxOutboxRows`/`eventsMaxInFlight` for high event throughput; `payloadMaxBytes` for capture size.

package/skill/reference/events.md

@@ -0,0 +1,102 @@
+# Events — durable pub/sub
+
+At-least-once delivery through a local SQLite outbox → runtime → subscribers. Fan-out to every matching subscriber, retries, and a dead-letter queue (operated from the dashboard, not the SDK).
+
+## Declare an event
+
+```ts
+sb.event.define(name: string, spec?: SchemaSpec): void
+```
+
+- Call before `await sb.start()`, on **both** publisher and subscriber (each indexes schemas locally to encode/decode; there's no global decoder registry).
+- `name` must match `^[a-z0-9_-]+(\.[a-z0-9_-]+)*$` (dotted segments, lowercase). A bad name throws `InvalidEventNameError`.
+- **Schema:** the proto needs a `service` block, and you reference the message by `method` — the SDK resolves the input message from the rpc of that name. (Event names contain dots, so they can't be rpc names directly; pick a valid rpc identifier for `method`.) Alternatively pass explicit `input` **and** `output`. Passing `input` alone does **not** resolve.
+
+```proto
+// events.proto
+syntax = "proto3";
+package billing;
+message ChargedEvent { string charge_id = 1; double amount = 2; }
+service BillingEvents {
+  // method for event.define; output is irrelevant for events but the block requires one.
+  rpc billing_charged (ChargedEvent) returns (ChargedEvent);
+}
+```
+
+## Handle (subscribe)
+
+```ts
+sb.event.handle(name: string, fn: (payload: unknown) => Promise<void> | void): void
+```
+
+- **Exact event name** — not a wildcard. (Wildcard subscription routing is a server-side concern, not the handler string.)
+- Register before `start()`. A single instance may register several handlers; each matching event fires all of them.
+- **Handlers must be idempotent.** Delivery is at-least-once. Throwing causes a Nack → retry → DLQ after the runtime's max attempts. Returning normally Acks.
+
+```ts
+sb.event.define("billing.charged", { protoFile: "./events.proto", method: "billing_charged" });
+sb.event.handle("billing.charged", async (payload) => {
+  const e = payload as { charge_id: string; amount: number };
+  await applyOnce(e.charge_id, e.amount); // idempotent by charge_id
+});
+await sb.start();
+```
+
+## Publish
+
+```ts
+await sb.event.publish<T>(
+  name: string,
+  payload: T,
+  opts?: PublishOpts,
+): Promise<{ eventId: string }>
+```
+
+- Call **after** `await sb.start()`. The event must be `define()`d first.
+- The payload is validated against the schema before it enters the outbox; encoding errors throw synchronously.
+- Returns `{ eventId }` (a monotonic UUID).
+
+```ts
+sb.event.define("billing.charged", { protoFile: "./events.proto", method: "billing_charged" });
+await sb.start();
+const { eventId } = await sb.event.publish(
+  "billing.charged",
+  { charge_id: "ch-123", amount: 100 },
+  { idempotencyKey: "ch-123", partitionKey: "user-42" },
+);
+```
+
+> **Start the subscriber before the publisher.** Fan-out matches against registered subscriptions at publish time — a publish to a name nobody subscribes to yet is accepted but delivered to no one. After `start()`, the subscription registers asynchronously; in a script that publishes microseconds later, wait for the `connected` event (or briefly settle) before the first publish. Long-running services never hit this.
+
+### PublishOpts
+
+```ts
+interface PublishOpts {
+  idempotencyKey?: string;            // runtime dedups same key (24h window)
+  partitionKey?: string;             // FIFO ordering per key per consumer
+  fireAndForget?: boolean;           // skip the durable outbox (best-effort); default false
+  headers?: Record<string, string>; // metadata; not passed to the handler payload
+  occurredAtMs?: number;             // business timestamp; default now
+}
+```
+
+## Delivery semantics (what to rely on)
+
+- **At-least-once**: a handler may see the same event more than once → make it idempotent (use `idempotencyKey` on publish and/or a dedup key in the handler).
+- **Fan-out**: every subscriber whose subscription matches gets its own delivery.
+- **Ordering**: only guaranteed per `partitionKey`, per consumer.
+- **Retries + DLQ**: a throwing handler is retried by the runtime; after max attempts the delivery goes to the DLQ. Replay/purge the DLQ from the dashboard — the SDK has no DLQ API.
+
+## Errors
+
+```ts
+import { InvalidEventNameError, OutboxFullError } from "service-bridge";
+```
+
+- `InvalidEventNameError` — from `define()`/`publish()` when the name fails the regex.
+- `OutboxFullError` — from `publish()` when the local outbox hits `maxOutboxRows` (backpressure; default 100000). Slow down or raise the cap.
+- "no schema registered" — publishing/handling a name that was never `define()`d with a schema.
+
+## Capacity knobs (constructor options)
+
+`dataDir` (outbox location, default `./.servicebridge`), `maxOutboxRows` (100000), `eventsDrainerBatch` (50 rows/tick), `eventsMaxInFlight` (32 concurrent inbound handlers). See [configuration.md](configuration.md).

package/skill/reference/http-integrations.md

@@ -0,0 +1,87 @@
+# HTTP integrations — Express, Fastify, Hono
+
+ServiceBridge does **not** proxy your business HTTP. You run your own HTTP server; these plugins register its routes into the Service Map and Service Discovery and add trace/metric capture. Your framework keeps serving traffic exactly as before.
+
+Each plugin ships as a subpath export:
+
+```ts
+import { attachExpress } from "service-bridge/express";
+import { sbFastify }    from "service-bridge/fastify";
+import { attachHono }   from "service-bridge/hono";
+```
+
+All three: parse the `X-SB-Trace` header so handler-internal `sb.rpc.call`/`sb.event.publish` join the same trace, emit an `HTTP.HANDLE` op per request (status + optional body capture), and publish your routes + advertise endpoint. Safe to call before `sb.start()` — the endpoint queues into the first registration.
+
+## Express
+
+```ts
+attachExpress(app: Express, sb: ServiceBridge, endpoint: { host?: string; port: number }): void
+```
+
+Call **after** all routes are registered. `port` is required (Express can bind `0`, so the plugin can't infer it). Mount a body parser (`express.json()`) before routes so request bodies are captured.
+
+```ts
+import express from "express";
+import { ServiceBridge } from "service-bridge";
+import { attachExpress } from "service-bridge/express";
+
+const sb = new ServiceBridge("localhost:14445", process.env.API_KEY!);
+const app = express();
+app.use(express.json());
+app.get("/api/orders/:id", (req, res) => res.json({ id: req.params.id }));
+app.post("/api/orders", (req, res) => res.json({ created: true }));
+
+attachExpress(app, sb, { host: process.env.POD_IP, port: 3000 }); // after routes
+await sb.start();
+app.listen(3000);
+```
+
+## Fastify
+
+```ts
+await app.register(sbFastify, { sb: ServiceBridge, host?: string });
+```
+
+Register **before** your routes (it collects them via the `onRoute` hook) — the advertise endpoint is published after `app.listen()` via the `onListen` hook, so the real port (even `0`) is known automatically. Supports Fastify 4.x and 5.x.
+
+```ts
+import Fastify from "fastify";
+import { ServiceBridge } from "service-bridge";
+import { sbFastify } from "service-bridge/fastify";
+
+const sb = new ServiceBridge("localhost:14445", process.env.API_KEY!);
+const app = Fastify();
+await app.register(sbFastify, { sb, host: process.env.POD_IP });  // before routes
+app.get("/api/orders/:id", async (req) => ({ id: (req.params as any).id }));
+app.post("/api/orders", async () => ({ created: true }));
+
+await sb.start();
+await app.listen({ port: 3000 });
+```
+
+## Hono
+
+```ts
+attachHono(app: Hono, sb: ServiceBridge, endpoint: { host?: string; port: number }): void
+```
+
+Call **after** routes are registered. Hono doesn't bind a socket itself, so `port` must be passed and must match what you give `Bun.serve` / `@hono/node-server` / `Deno.serve`. Routes declared with `app.all(...)` are not collected (no concrete method).
+
+```ts
+import { Hono } from "hono";
+import { ServiceBridge } from "service-bridge";
+import { attachHono } from "service-bridge/hono";
+
+const sb = new ServiceBridge("localhost:14445", process.env.API_KEY!);
+const app = new Hono();
+app.get("/api/orders/:id", (c) => c.json({ id: c.req.param("id") }));
+app.post("/api/orders", (c) => c.json({ created: true }));
+
+attachHono(app, sb, { host: process.env.POD_IP, port: 3000 }); // after routes
+await sb.start();
+export default { port: 3000, fetch: app.fetch }; // Bun
+```
+
+## Advertise host
+
+`host` is optional on all three. If omitted, the plugin falls back to `SB_HTTP_ADVERTISE_HOST` → `SB_ADVERTISE_HOST` → `127.0.0.1` (with a one-time warning). Pass an explicit reachable host (e.g. the pod IP) in production.

package/skill/reference/jobs.md

@@ -0,0 +1,90 @@
+# Jobs — scheduled work
+
+Cron, delayed, and interval jobs driven by the runtime. The runtime fires the job on schedule, leases it to one instance, and retries on failure. Jobs have no incoming caller and no payload.
+
+## Register a job
+
+```ts
+sb.job.handle(name: string, opts: JobOpts, fn: (ctx: JobHandlerCtx) => Promise<void>): void
+```
+
+Register before `await sb.start()`. Names must be unique per service (duplicate throws).
+
+```ts
+interface JobOpts {
+  trigger: Trigger;            // required — exactly one shape below
+  catchup?: CatchupPolicy;     // "skip" (default) | "fire_once" | "fire_all"
+  overlap?: OverlapPolicy;     // "skip" (default) | "allow" | "buffer_one"
+  deps?: DeclaredDep[];        // declared downstream dependencies
+  maxAttempts?: number;
+  leaseTtlMs?: number;
+  maxConcurrent?: number;      // with overlap "allow"
+  retry?: RetryPolicy;         // { initialMs, maxMs, multiplier, jitter }
+}
+
+type Trigger =
+  | { cron: string; tz?: string }              // 5-field cron, no seconds; e.g. "0 9 * * 1"
+  | { delayed: { at: Date | string | number } }
+  | { interval: number };                       // milliseconds
+
+type DeclaredDep = { rpc: string } | { event: string } | { workflow: string };  // rpc form: "service.Method"
+```
+
+## Handler context
+
+```ts
+interface JobHandlerCtx {
+  jobName: string;
+  executionId: string;
+  scheduledAt: Date;        // UTC fire time
+  localScheduledAt: Date;   // in the cron tz (UTC for interval/delayed)
+  attempt: number;          // 1,2,3… diagnostic only — DO NOT dedup on this
+  idempotencyKey: string;   // stable per (job, scheduled tick) — DEDUP ON THIS
+  signal: AbortSignal;      // aborts on lease loss / reconnect
+}
+```
+
+**Idempotency:** a tick may be delivered more than once (retry, failover). Dedup on `ctx.idempotencyKey` (e.g. a DB unique constraint or `SET NX`), never on `ctx.attempt`. Respect `ctx.signal` for long jobs.
+
+## Policies
+
+- `catchup` — after the runtime was down across scheduled ticks: `skip` (ignore them), `fire_once` (one catch-up run), `fire_all` (replay all missed, capped by runtime budget).
+- `overlap` — when the previous run is still going: `skip` (drop this tick), `buffer_one` (queue one), `allow` (run up to `maxConcurrent` concurrently).
+
+## Recipe — cron job that calls an RPC
+
+```ts
+import { ServiceBridge } from "service-bridge";
+const sb = new ServiceBridge("localhost:14445", process.env.JOBS_KEY!);
+
+sb.service("billing", { rpc: ["Reconcile"] }); // declare the downstream call
+sb.job.handle(
+  "nightly-reconcile",
+  {
+    trigger: { cron: "0 2 * * *", tz: "Europe/Moscow" },  // 02:00 Moscow daily
+    catchup: "fire_once",
+    overlap: "skip",
+    maxAttempts: 3,
+    deps: [{ rpc: "billing.Reconcile" }],
+  },
+  async (ctx) => {
+    if (!(await claimOnce(ctx.idempotencyKey))) return; // idempotency guard
+    await sb.rpc.call("billing", "Reconcile", { date: ctx.localScheduledAt.toISOString() });
+  },
+);
+
+await sb.start();
+```
+
+## Recipe — one-shot delayed job
+
+```ts
+sb.job.handle(
+  "send-reminder",
+  { trigger: { delayed: { at: Date.now() + 60_000 } }, maxAttempts: 2 },
+  async (ctx) => { await sendReminder(ctx.idempotencyKey); },
+);
+await sb.start();
+```
+
+Per-service job rate limits are enforced by the runtime at registration time; tune them in the dashboard, not the SDK.

package/skill/reference/rpc.md

@@ -0,0 +1,150 @@
+# RPC — request/response
+
+Direct, typed request/response between services. The runtime resolves routing by service name; you never hardcode host/port.
+
+## Handle incoming calls
+
+```ts
+sb.rpc.handle<Req, Res>(
+  name: string,
+  fn: (req: Req) => Promise<Res> | Res,
+  opts: { schema: SchemaSpec; captureMode?: "all" | "errors" | "none" },
+): void
+```
+
+- `schema` is **required**. See [Schemas](#schemas).
+- Register before `await sb.start()`.
+- Throw from the handler to signal failure to the caller; the runtime maps it to an error response.
+
+```ts
+sb.rpc.handle(
+  "Charge",
+  async (req: { userId: string; amount: number }) => {
+    if (req.amount <= 0) throw new Error("amount must be positive");
+    return { transactionId: `tx-${req.userId}`, ok: true };
+  },
+  { schema: { protoFile: "./payment.proto", input: "ChargeRequest", output: "ChargeReply" } },
+);
+```
+
+## Call another service
+
+Two ways. Prefer the typed client for ergonomics; use `rpc.call` for dynamic/low-level calls.
+
+### Typed client (recommended)
+
+```ts
+const payment = await sb.client(
+  serviceName: string,
+  protoFile: string,
+  opts?: { methods?: string[]; callDefaults?: CallOpts },
+); // returns a proxy with one method per rpc in the .proto service block
+```
+
+```ts
+const payment = await sb.client("payment-svc", "./payment.proto");
+await sb.start();
+const res = await payment.Charge({ userId: "u-1", amount: 100 });
+```
+
+`client()` reads the `.proto` once, declares every method in its `service` block as an outgoing dependency, and loads schemas. Call `client()` **before** `start()` so the dependency rides along in the first registration. Calls succeed once `start()` has connected.
+
+### Low-level call
+
+```ts
+await sb.rpc.call<Req, Res>(
+  serviceName: string,
+  methodName: string,
+  payload: Req,
+  opts?: CallOpts,
+): Promise<Res>
+```
+
+When using `rpc.call` for a method whose schema the SDK doesn't yet know, register it first with `sb.useSchema(serviceName, methodName, spec)` (before `start()`), or declare the dependency with `sb.service(serviceName, { rpc: ["Method"] })`.
+
+```ts
+sb.service("payment-svc", { rpc: ["Charge"] });
+await sb.useSchema("payment-svc", "Charge", {
+  protoFile: "./payment.proto", input: "ChargeRequest", output: "ChargeReply",
+});
+await sb.start();
+const res = await sb.rpc.call("payment-svc", "Charge", { userId: "u-1", amount: 100 }, { timeout: "15s" });
+```
+
+### CallOpts
+
+```ts
+interface CallOpts {
+  timeout?: string;                          // "10s", "500ms" — default "30s"
+  requestId?: string;                        // auto UUID v4 if omitted
+  transport?: "direct" | "proxy" | "auto";   // default "auto" (direct when endpoint known, else proxy)
+  idempotencyKey?: string;                   // opt-in runtime-side dedup; empty = no dedup
+  retry?: Partial<RetryOpts>;                // defaults below
+}
+
+interface RetryOpts {
+  maxAttempts: number;   // default 3
+  baseDelayMs: number;   // default 200
+  factor: number;        // default 2
+  maxDelayMs: number;    // default 5000
+  jitter: number;        // [0,1], default 0.3
+}
+```
+
+Per-call opts override `callDefaults` from the constructor.
+
+## Streaming
+
+Server-streaming: handler returns an async iterable; caller consumes one.
+
+```ts
+// provider
+sb.rpc.handleStream<Req, Chunk>(
+  name: string,
+  fn: (req: Req) => AsyncIterable<Chunk>,
+  opts: { schema: SchemaSpec },
+): void
+
+// caller — typed client method returns an async iterable, or use sb.stream:
+sb.stream<Req, Chunk>(serviceName, methodName, payload, opts?): AsyncIterable<Chunk>
+```
+
+```ts
+sb.rpc.handleStream("Ticks", async function* (req: { n: number }) {
+  for (let i = 0; i < req.n; i++) yield { i };
+}, { schema: { protoFile: "./ticks.proto", input: "TicksRequest", output: "Tick" } });
+
+// caller
+for await (const chunk of sb.stream("tick-svc", "Ticks", { n: 5 })) {
+  console.log(chunk);
+}
+```
+
+## Schemas
+
+Every RPC handler and every declared call needs a schema. Two forms:
+
+```ts
+type SchemaSpec =
+  | { protoFile: string; input?: string; output?: string; method?: string }
+  | { schemaFile: string; method?: string };   // .schema.json with explicit fieldNumber per property
+```
+
+- With `protoFile` and no `input`/`output`, the SDK finds the rpc in the `.proto` `service` block whose name matches the method and uses its request/response messages. Provide `input`/`output` explicitly when the message names differ from the auto-resolution or there's ambiguity.
+- Paths are relative to `process.cwd()` unless absolute.
+
+## Errors
+
+- `RpcAccessDeniedError` (`serviceName`, `methodName`, `reason`) — thrown from `rpc.call` when the runtime's bilateral access policy denies the call. Not retryable.
+- Handler exceptions surface to the caller as an error response.
+- Connection/auth failures surface via the `disconnected` event with a `ServiceBridgeError` (see [configuration.md](configuration.md)).
+
+```ts
+import { RpcAccessDeniedError } from "service-bridge";
+try {
+  await sb.rpc.call("payment-svc", "Charge", payload);
+} catch (e) {
+  if (e instanceof RpcAccessDeniedError) { /* policy denial — fix the access policy */ }
+  else throw e;
+}
+```

package/skill/reference/workflows.md

@@ -0,0 +1,150 @@
+# Workflows — durable orchestration
+
+A workflow is a DAG of steps persisted in the runtime: steps run in parallel by default and order only by their `waitFor` dependencies. The runtime drives execution, survives restarts, supports compensation (saga rollback), external signals, and replay.
+
+There are two sides: the **owner** registers the definition (`workflow.handle`); a **caller** launches runs (`workflow.start`). They can be the same service or different ones.
+
+## Define & register (owner side)
+
+```ts
+sb.workflow.handle(name: string, def: WorkflowDef, opts?: { input?: Record<string, unknown> }): void
+
+interface WorkflowDef {
+  input?: Record<string, unknown>;   // JSON-Schema-ish shape for run input
+  steps: Step[];                      // the DAG
+  retry?: Partial<RetryOpts>;         // default retry for steps
+  maxParallelism?: number;            // cap concurrent steps (0 = unlimited)
+  timeoutSec?: number;                // whole-run wall-clock timeout
+}
+```
+
+Register before `await sb.start()`. The definition is canonicalized and fingerprinted; the runtime rejects re-registering the same name with a different shape while runs exist (in-flight runs keep their frozen plan).
+
+## Step types
+
+Every step shares these control fields:
+
+```ts
+interface StepControlFields {
+  id: string;                    // unique within the workflow, ^[a-z0-9_]+$
+  waitFor?: string[];            // ids that must finish first (this is what orders the DAG)
+  when?: Predicate;              // run only if predicate is true (see below)
+  compensate?: CompensateSpec;   // rollback action if the run later fails (call/publish steps)
+  timeoutSec?: number;           // workflow-control timeout for this step
+  retry?: Partial<RetryOpts>;
+}
+```
+
+| `type` | Extra fields | Does |
+|---|---|---|
+| `"call"` | `service`, `method`, `input`, `opts?` | `rpc.call` to another service |
+| `"publish"` | `event`, `input`, `opts?` | publish an event |
+| `"sleep"` | `durationSec` | durable timer |
+| `"wait_event"` | `event`, `filter?` | park until a matching event is ingested |
+| `"wait_signal"` | `signal` | park until `sb.workflow.signal(runId, signal, …)` |
+| `"workflow"` | `workflow`, `input`, `opts?` | start a child workflow and wait for it |
+| `"parallel"` | `steps`, `forEach?` | group; all inner steps start at once |
+| `"sequence"` | `steps`, `forEach?` | group; inner steps run one after another |
+| `"local"` | `fn: (state) => Promise<unknown>` | arbitrary JS in the SDK process — use sparingly |
+
+`forEach?: { from: JsonExpression; as: string }` on parallel/sequence fans the group out over an array.
+
+## Expressions (JSONPath-lite)
+
+Step `input`, `when`, `idempotencyKey`, `forEach.from`, etc. accept declarative expressions:
+
+- `"$.input.userId"` — a path into run input or accumulated state. Each completed step's output is stored under its `id`, so `"$.reserve.token"` reads the `reserve` step's output field `token`.
+- A string **not** starting with `$.` is a literal. Use `{ literal: "$.x" }` to force a literal that looks like a path.
+- Objects/arrays are evaluated recursively.
+
+`Predicate` for `when`:
+
+```ts
+type Predicate =
+  | string                                  // truthy expression, e.g. "$.input.enabled"
+  | { not: Predicate }
+  | { equals: [JsonExpression, JsonExpression] }
+  | { in: [JsonExpression, JsonExpression] }   // [value, array]
+  | { and: Predicate[] }
+  | { or: Predicate[] };
+```
+
+`CompensateSpec` (rollback for a `call`/`publish` step, run in reverse if a later step fails):
+
+```ts
+interface CompensateSpec {
+  type?: "call" | "publish";
+  service?: string; method?: string;   // for call
+  event?: string;                       // for publish
+  input: JsonExpression;
+  retry?: Partial<RetryOpts>;
+  idempotencyKey?: string;
+}
+```
+
+## Launch & observe (caller side)
+
+```ts
+await sb.workflow.start(name, input, opts?): Promise<{ runId: string }>   // opts: { idempotencyKey?, timeoutSec?, parentRunId? }
+await sb.workflow.await(runId): Promise<Record<string, unknown>>          // resolves on success, rejects on failed/cancelled
+await sb.workflow.query(runId): Promise<{ status; state; steps }>         // point-in-time snapshot
+await sb.workflow.signal(runId, signalName, payload): Promise<void>       // deliver to a wait_signal step
+await sb.workflow.cancel(runId): Promise<void>                            // cooperative cancel → compensating → cancelled
+await sb.workflow.replay(runId, opts?): Promise<{ runId: string }>        // fork a new run; opts: { fromStepId? }
+```
+
+Caller ops require `await sb.start()` first. `query().status` is one of `pending | running | waiting | success | failed | cancelling | cancelled | compensating | failed_compensated`.
+
+> When the **same instance** both `handle()`s a workflow and `start()`s it, the definition registers asynchronously after `start()` — a `start()` issued microseconds later can throw `WorkflowNotFoundError`. Wait for the `connected` event (or briefly settle) first. With a separate owner service (the usual case), this doesn't apply.
+
+## Recipe — saga with compensation
+
+```ts
+// owner
+sb.workflow.handle("checkout", {
+  input: { userId: "string", item: "string", quantity: "number", amount: "number" },
+  steps: [
+    {
+      type: "call", id: "reserve",
+      service: "inventory", method: "Reserve",
+      input: { item: "$.input.item", quantity: "$.input.quantity" },
+      compensate: { service: "inventory", method: "Release", input: { token: "$.reserve.token" } },
+    },
+    {
+      type: "call", id: "charge",
+      service: "billing", method: "Charge",
+      input: { userId: "$.input.userId", amount: "$.input.amount" },
+      waitFor: ["reserve"],
+      // if "charge" fails, the runtime runs "reserve"'s compensate (Release) automatically
+    },
+    {
+      type: "publish", id: "notify",
+      event: "order.placed",
+      input: { userId: "$.input.userId", token: "$.reserve.token" },
+      waitFor: ["charge"],
+    },
+  ],
+  retry: { maxAttempts: 3 },
+});
+await sb.start();
+```
+
+```ts
+// caller
+await sb.start();
+const { runId } = await sb.workflow.start("checkout", {
+  userId: "u-1", item: "sku-9", quantity: 2, amount: 100,
+});
+const finalState = await sb.workflow.await(runId);
+```
+
+## Errors
+
+```ts
+import { WorkflowAccessDeniedError, WorkflowNotFoundError, WorkflowTerminalError } from "service-bridge";
+```
+
+- `WorkflowNotFoundError` — `start()` on an unregistered name.
+- `WorkflowAccessDeniedError` — bilateral access policy denied the start.
+- `WorkflowTerminalError` — `signal()`/`cancel()` on an already-terminal run.
+- `await(runId)` rejects when the run ends in `failed`/`cancelled`/`failed_compensated`.