@rotorsoft/act-http 1.6.0 → 1.7.0

package/dist/@types/api/index.d.ts

@@ -36,4 +36,5 @@
 export type { ActorExtractor } from "./actor.js";
 export { type ApiError, ERROR_MAP, type ErrorMapEntry, toApiError, } from "./errors.js";
 export { type IdempotencyResult, withIdempotency } from "./idempotency.js";
+export { DEFAULT_SSE_HEARTBEAT_MS, DEFAULT_SSE_MAX_CONNECTIONS, fireAndForget, resolveSseConfig, runSseSubscription, type SseAccounting, type SseConfig, SseConnectionCounter, type SseOptions, type SseSubscriptionFrame, } from "./sse-wiring.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/@types/api/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EACL,KAAK,QAAQ,EACb,SAAS,EACT,KAAK,aAAa,EAClB,UAAU,GACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,iBAAiB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EACL,KAAK,QAAQ,EACb,SAAS,EACT,KAAK,aAAa,EAClB,UAAU,GACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,iBAAiB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EACL,wBAAwB,EACxB,2BAA2B,EAC3B,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,oBAAoB,EACpB,KAAK,UAAU,EACf,KAAK,oBAAoB,GAC1B,MAAM,iBAAiB,CAAC"}

package/dist/@types/api/sse-wiring.d.ts

@@ -0,0 +1,166 @@
+import type { BroadcastChannel } from "../sse/broadcast.js";
+import type { BroadcastState } from "../sse/types.js";
+/**
+ * SSE wiring options shared by the auto-generated `trpc` and `hono`
+ * transports. When supplied, each transport emits one streaming
+ * subscription per registered state name, all reading from the same
+ * host-supplied {@link BroadcastChannel}.
+ *
+ * The host owns publication: every `app.do(...)` call site must
+ * forward the resulting snapshots to `channel.publish(...)` for
+ * subscribers to see updates. The framework deliberately doesn't
+ * auto-publish because the derived state usually needs app-specific
+ * overlays (presence, computed fields) that only the host can supply.
+ *
+ * Defaults are sized for typical business-app dashboards (dozens to
+ * hundreds of human viewers per process). Both numeric knobs are
+ * validated at transport-function construction; out-of-range values
+ * throw `RangeError` immediately so misconfiguration surfaces at
+ * startup instead of at first connection.
+ */
+export type SseOptions = {
+    /**
+     * The {@link BroadcastChannel} the generator's subscriptions hook
+     * into. Host owns its lifecycle; the generator does not construct
+     * one for you because the channel's `<S>` shape is app-specific and
+     * passing it in keeps the type chain typed end-to-end at the host.
+     */
+    readonly channel: BroadcastChannel<any>;
+    /**
+     * Hard cap on concurrent open subscriptions per generator
+     * instance. The 501st simultaneous open returns `503` (Hono) or
+     * throws `TOO_MANY_REQUESTS` (tRPC) — never a silent stall.
+     *
+     * Default `500`. Validated range `[1, 10_000]`. Above 10k the
+     * framework refuses to construct: at that point the FD ceiling
+     * and per-connection memory force horizontal scaling regardless
+     * of tuning, so the right move is sticky LB + per-process cap,
+     * not a higher single-process limit.
+     */
+    readonly maxConnections?: number;
+    /**
+     * Keep-alive cadence in milliseconds. Most reverse proxies idle
+     * connections out after ~60 seconds; the default `30_000` stays
+     * comfortably under.
+     *
+     * Validated range `[15_000, 300_000]`. Under 15 s wastes
+     * bandwidth on a business workload; over 5 min risks proxy drops.
+     */
+    readonly heartbeatMs?: number;
+};
+/**
+ * Resolved SSE configuration after validation and default expansion.
+ * Internal — the resolved values are what every transport actually
+ * runs against.
+ *
+ * @internal
+ */
+export type SseConfig = {
+    readonly channel: BroadcastChannel<BroadcastState>;
+    readonly maxConnections: number;
+    readonly heartbeatMs: number;
+};
+/**
+ * Default cap on concurrent open subscriptions per generator
+ * instance. Sized for typical business-app dashboards (dozens to a
+ * few hundred viewers); high enough not to surprise small
+ * deployments, low enough not to mask a missing horizontal-scale
+ * strategy on big ones.
+ */
+export declare const DEFAULT_SSE_MAX_CONNECTIONS = 500;
+/**
+ * Default keep-alive cadence (30 s). Sits comfortably under the
+ * 60 s idle timeout most reverse proxies impose.
+ */
+export declare const DEFAULT_SSE_HEARTBEAT_MS = 30000;
+/**
+ * Validate and apply defaults to host-supplied {@link SseOptions}.
+ *
+ * Throws `RangeError` when either numeric knob is outside its
+ * documented range. Pure: same input → same output, no side
+ * effects, no I/O. Each transport calls this once at the start of
+ * `hono(...)` / `trpc(...)`.
+ */
+export declare function resolveSseConfig(options: SseOptions): SseConfig;
+/**
+ * Per-generator concurrent-open counter. Constructed once inside
+ * `hono(...)` / `trpc(...)` and consulted at every subscription
+ * open: failure to acquire means the cap has been hit and the
+ * transport reports `503` / `TOO_MANY_REQUESTS` to the caller.
+ *
+ * The counter is intentionally process-local. SSE doesn't multiplex
+ * across processes; operators wanting more than `maxConnections`
+ * viewers run multiple processes behind a sticky load balancer.
+ */
+export declare class SseConnectionCounter {
+    readonly limit: number;
+    private _open;
+    constructor(limit: number);
+    /**
+     * Reserve one slot. Returns `true` when accepted (caller must
+     * eventually {@link release} the slot, even on error paths) or
+     * `false` when the cap is already reached.
+     */
+    acquire(): boolean;
+    /**
+     * Free a previously-{@link acquire}d slot. Always runs from a
+     * `finally` block in the transport's subscription handler so
+     * crashed handlers don't leak count.
+     */
+    release(): void;
+    /** Currently-open count. Test/observability hook. */
+    get open(): number;
+}
+/**
+ * Wrap a fire-and-forget Promise-returning operation so its
+ * rejection is swallowed in place of leaking an unhandled
+ * rejection. Used by the Hono heartbeat tick (the interval callback
+ * isn't `await`ed, so its rejection has nowhere to go) and by any
+ * other "best-effort write" the transports run.
+ *
+ * Pure: same input → same output, no side effects on the caller.
+ * Returns the chained Promise so the caller can also `await`
+ * completion if they want to (the Hono heartbeat doesn't).
+ */
+export declare function fireAndForget<T>(op: () => Promise<T>): Promise<T | undefined>;
+/**
+ * Frame yielded by the per-state SSE subscription generator. The
+ * initial cached state (when present) arrives as `kind: "state"`;
+ * every subsequent broadcast publication arrives as `kind: "patch"`
+ * with the channel's `PatchMessage` payload.
+ */
+export type SseSubscriptionFrame<S> = {
+    readonly kind: "state";
+    readonly data: S;
+} | {
+    readonly kind: "patch";
+    readonly data: unknown;
+};
+/**
+ * Subscription accounting hook. Implementations have a chance to
+ * acquire a slot before the loop starts and to release it once the
+ * loop's `finally` block runs — used by the tRPC side to enforce
+ * `maxConnections` from inside the generator, where it can throw
+ * `TRPCError` cleanly. Hono enforces the cap outside the loop (so a
+ * full counter returns `503` *before* streamSSE writes headers), then
+ * passes `undefined` here.
+ */
+export type SseAccounting = {
+    acquire(): boolean;
+    release(): void;
+};
+/**
+ * The shared subscription loop both transports run. Optionally
+ * acquires one slot on the supplied {@link SseAccounting}, yields the
+ * cached state (when present), then forwards every channel
+ * publication as a `kind: "patch"` frame until either the consumer
+ * breaks (calling `iter.return()`) or the supplied abort signal fires.
+ *
+ * Exported as the testable seam — the Hono and tRPC sibling
+ * generators wrap this so the signal-driven cleanup and counter
+ * accounting live in one place.
+ */
+export declare function runSseSubscription<S extends {
+    _v: number;
+} = any>(channel: BroadcastChannel<S>, stream_id: string, accounting: SseAccounting | undefined, signal: AbortSignal | undefined, on_cap_exceeded?: () => never): AsyncGenerator<SseSubscriptionFrame<S>>;
+//# sourceMappingURL=sse-wiring.d.ts.map

package/dist/@types/api/sse-wiring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-wiring.d.ts","sourceRoot":"","sources":["../../../src/api/sse-wiring.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB;;;;;OAKG;IAEH,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACxC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC,cAAc,CAAC,CAAC;IACnD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C;;;GAGG;AACH,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAO/C;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,CA0B/D;AAED;;;;;;;;;GASG;AACH,qBAAa,oBAAoB;IAC/B,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,OAAO,CAAC,KAAK,CAAK;gBAEN,KAAK,EAAE,MAAM;IAIzB;;;;OAIG;IACH,OAAO,IAAI,OAAO;IAMlB;;;;OAIG;IACH,OAAO,IAAI,IAAI;IAIf,qDAAqD;IACrD,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAE7E;AAED;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GAC5C;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEvD;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,IAAI,OAAO,CAAC;IACnB,OAAO,IAAI,IAAI,CAAC;CACjB,CAAC;AAEF;;;;;;;;;;GAUG;AAEH,wBAAuB,kBAAkB,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,GAAG,EACtE,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC5B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,aAAa,GAAG,SAAS,EACrC,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,eAAe,CAAC,EAAE,MAAM,KAAK,GAC5B,cAAc,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAgCzC"}

package/dist/@types/hono/index.d.ts

@@ -2,7 +2,7 @@ import type { Actor, Target } from "@rotorsoft/act";
 import type { IdempotencyStore } from "@rotorsoft/act-ops/idempotency";
 import type { Context, MiddlewareHandler } from "hono";
 import { Hono } from "hono";
-import { type ActorExtractor } from "../api/index.js";
+import { type ActorExtractor, type SseOptions } from "../api/index.js";
 /**
  * Hono context variables this subpath contributes. The generic on
  * the returned middleware threads it through so routes downstream
@@ -46,6 +46,23 @@ export type HonoOptions = {
         readonly store: IdempotencyStore;
         readonly keyFrom?: (c: Context) => string | undefined;
     };
+    /**
+     * Optional SSE wiring. When set, the generator emits one
+     * `GET <basePath>/sse/<stateName>?stream=<streamId>` per unique
+     * state name in the registry. The endpoint runs the host
+     * {@link actor} extractor, looks up the streamId from
+     * `?stream=...`, opens a `text/event-stream`, yields the cached
+     * state (if any), and forwards every patch published to the
+     * shared {@link SseOptions.channel}. A heartbeat keeps proxies
+     * from idling the connection out; the per-process connection cap
+     * returns `503 Service Unavailable` (with `Retry-After: 1`) when
+     * full so operators never see silent stalls.
+     *
+     * Off by default — most APIs don't expose live state to every
+     * client, and opening one is widening both the auth and cost
+     * surface.
+     */
+    readonly sse?: SseOptions;
     readonly basePath?: string;
 };
 /**

package/dist/@types/hono/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hono/index.ts"],"names":[],"mappings":"AAgDA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AACvD,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EACL,KAAK,cAAc,EAIpB,MAAM,iBAAiB,CAAC;AAEzB;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,KAAK,EAAE,KAAK,CAAC;CACd,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,CACf,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,OAAO,EACd,CAAC,EAAE,OAAO,KACP,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9B,QAAQ,CAAC,eAAe,CAAC,EAAE,CACzB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,OAAO,EACd,CAAC,EAAE,OAAO,KACP,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACtD,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;QACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;KACvD,CAAC;IACF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,cAAc,GACxB,iBAAiB,CAAC;IAAE,SAAS,EAAE,sBAAsB,CAAA;CAAE,CAAC,CAe1D;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH;;;;;;;;GAQG;AACH,KAAK,UAAU,GAAG;IAChB,QAAQ,CAAC,QAAQ,EAAE;QACjB,OAAO,EAAE,MAAM,CACb,MAAM,EACN;YACE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;YACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;SAC3C,CACF,CAAC;KACH,CAAC;IACF,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACxE,CAAC;AAEF,wBAAgB,IAAI,CAAC,IAAI,SAAS,UAAU,GAAG,UAAU,EACvD,GAAG,EAAE,IAAI,EACT,OAAO,EAAE,WAAW,GACnB,IAAI,CAAC;IAAE,SAAS,EAAE,sBAAsB,CAAA;CAAE,CAAC,CAyE7C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hono/index.ts"],"names":[],"mappings":"AAgDA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AACvD,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,EACL,KAAK,cAAc,EAMnB,KAAK,UAAU,EAGhB,MAAM,iBAAiB,CAAC;AAEzB;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,KAAK,EAAE,KAAK,CAAC;CACd,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,CACf,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,OAAO,EACd,CAAC,EAAE,OAAO,KACP,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9B,QAAQ,CAAC,eAAe,CAAC,EAAE,CACzB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,OAAO,EACd,CAAC,EAAE,OAAO,KACP,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACtD,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;QACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;KACvD,CAAC;IACF;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,cAAc,GACxB,iBAAiB,CAAC;IAAE,SAAS,EAAE,sBAAsB,CAAA;CAAE,CAAC,CAe1D;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH;;;;;;;;GAQG;AACH,KAAK,UAAU,GAAG;IAChB,QAAQ,CAAC,QAAQ,EAAE;QACjB,OAAO,EAAE,MAAM,CACb,MAAM,EACN;YACE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;YACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;SAC3C,CACF,CAAC;KACH,CAAC;IACF,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACxE,CAAC;AAEF,wBAAgB,IAAI,CAAC,IAAI,SAAS,UAAU,GAAG,UAAU,EACvD,GAAG,EAAE,IAAI,EACT,OAAO,EAAE,WAAW,GACnB,IAAI,CAAC;IAAE,SAAS,EAAE,sBAAsB,CAAA;CAAE,CAAC,CA0I7C"}

package/dist/@types/trpc/index.d.ts

@@ -53,7 +53,7 @@
 import type { Target } from "@rotorsoft/act";
 import type { IdempotencyStore } from "@rotorsoft/act-ops/idempotency";
 import { type AnyTRPCMiddlewareFunction, type AnyTRPCMutationProcedure, type AnyTRPCRootTypes, type TRPCBuiltRouter } from "@trpc/server";
-import { type ActorExtractor } from "../api/index.js";
+import { type ActorExtractor, type SseOptions } from "../api/index.js";
 /**
  * Per-call options for {@link trpc}. The host supplies the three
  * seams the package can't make decisions on:
@@ -95,6 +95,22 @@ export type TrpcOptions<Ctx> = {
         readonly store: IdempotencyStore;
         readonly keyFrom: (ctx: Ctx) => string | undefined;
     };
+    /**
+     * Optional SSE wiring. When set, the generator emits one
+     * subscription per unique state name in the registry, grouped on
+     * the returned router as
+     * `router.subscribe.<stateName>.useSubscription({ stream })`.
+     * Each subscription yields `{ kind: "state", data }` once with
+     * the cached state (when present) and then `{ kind: "patch",
+     * data }` for every patch the shared
+     * {@link SseOptions.channel} publishes. The per-process
+     * connection cap surfaces as a `TOO_MANY_REQUESTS` `TRPCError`.
+     *
+     * Off by default — most APIs don't expose live state to every
+     * client, and opening one is widening both the auth and cost
+     * surface.
+     */
+    readonly sse?: SseOptions;
 };
 /**
  * Build a tRPC middleware that runs an {@link ActorExtractor} once

package/dist/@types/trpc/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/trpc/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,OAAO,KAAK,EAAS,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EACL,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,EAErB,KAAK,eAAe,EAErB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,cAAc,EAGpB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,MAAM,WAAW,CAAC,GAAG,IAAI;IAC7B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,CACf,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,GAAG,KACL,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9B,QAAQ,CAAC,eAAe,CAAC,EAAE,CACzB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,GAAG,KACL,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACtD,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;QACjC,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM,GAAG,SAAS,CAAC;KACpD,CAAC;CACH,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,cAAc,GACxB,yBAAyB,CAmB3B;AA+CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH;;;;;;;;;;GAUG;AACH,KAAK,UAAU,GAAG;IAChB,QAAQ,CAAC,QAAQ,EAAE;QACjB,OAAO,EAAE,MAAM,CACb,MAAM,EACN;YACE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;YACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;SAC3C,CACF,CAAC;KACH,CAAC;IACF,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACxE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,KAAK,eAAe,CAAC,IAAI,IAAI,eAAe,CAC1C,gBAAgB,EAChB,IAAI,SAAS;IAAE,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;KAAE,CAAA;CAAE,GAClD;KAAG,CAAC,IAAI,MAAM,QAAQ,GAAG,wBAAwB;CAAE,GACnD,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAC7C,CAAC;AAEF,wBAAgB,IAAI,CAClB,GAAG,SAAS,MAAM,GAAG,MAAM,EAC3B,IAAI,SAAS,UAAU,GAAG,UAAU,EACpC,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,CAAC,GAAG,CAAC,GAAG,eAAe,CAAC,IAAI,CAAC,CAyE7D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/trpc/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,OAAO,KAAK,EAAS,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EACL,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,EAErB,KAAK,eAAe,EAErB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,KAAK,cAAc,EAInB,KAAK,UAAU,EAGhB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,MAAM,WAAW,CAAC,GAAG,IAAI;IAC7B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,CACf,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,GAAG,KACL,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9B,QAAQ,CAAC,eAAe,CAAC,EAAE,CACzB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,GAAG,KACL,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACtD,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;QACjC,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM,GAAG,SAAS,CAAC;KACpD,CAAC;IACF;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,UAAU,CAAC;CAC3B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,cAAc,GACxB,yBAAyB,CAmB3B;AA+CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH;;;;;;;;;;GAUG;AACH,KAAK,UAAU,GAAG;IAChB,QAAQ,CAAC,QAAQ,EAAE;QACjB,OAAO,EAAE,MAAM,CACb,MAAM,EACN;YACE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;YACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;SAC3C,CACF,CAAC;KACH,CAAC;IACF,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACxE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,KAAK,eAAe,CAAC,IAAI,IAAI,eAAe,CAC1C,gBAAgB,EAChB,IAAI,SAAS;IAAE,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;KAAE,CAAA;CAAE,GAClD;KAAG,CAAC,IAAI,MAAM,QAAQ,GAAG,wBAAwB;CAAE,GACnD,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAC7C,CAAC;AAEF,wBAAgB,IAAI,CAClB,GAAG,SAAS,MAAM,GAAG,MAAM,EAC3B,IAAI,SAAS,UAAU,GAAG,UAAU,EACpC,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,CAAC,GAAG,CAAC,GAAG,eAAe,CAAC,IAAI,CAAC,CAsG7D"}

package/dist/api/index.cjs

@@ -20,7 +20,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/api/index.ts
 var api_exports = {};
 __export(api_exports, {
+  DEFAULT_SSE_HEARTBEAT_MS: () => DEFAULT_SSE_HEARTBEAT_MS,
+  DEFAULT_SSE_MAX_CONNECTIONS: () => DEFAULT_SSE_MAX_CONNECTIONS,
   ERROR_MAP: () => ERROR_MAP,
+  SseConnectionCounter: () => SseConnectionCounter,
+  fireAndForget: () => fireAndForget,
+  resolveSseConfig: () => resolveSseConfig,
+  runSseSubscription: () => runSseSubscription,
   toApiError: () => toApiError,
   withIdempotency: () => withIdempotency
 });
@@ -76,9 +82,107 @@ async function withIdempotency(store, key, handler) {
   }
   return { deduped: false, result: await handler() };
 }
+
+// src/api/sse-wiring.ts
+var DEFAULT_SSE_MAX_CONNECTIONS = 500;
+var DEFAULT_SSE_HEARTBEAT_MS = 3e4;
+var MAX_CONNECTIONS_MIN = 1;
+var MAX_CONNECTIONS_MAX = 1e4;
+var HEARTBEAT_MS_MIN = 15e3;
+var HEARTBEAT_MS_MAX = 3e5;
+function resolveSseConfig(options) {
+  const max_connections = options.maxConnections ?? DEFAULT_SSE_MAX_CONNECTIONS;
+  const heartbeat_ms = options.heartbeatMs ?? DEFAULT_SSE_HEARTBEAT_MS;
+  if (!Number.isFinite(max_connections) || max_connections < MAX_CONNECTIONS_MIN || max_connections > MAX_CONNECTIONS_MAX) {
+    throw new RangeError(
+      `sse.maxConnections must be in [${MAX_CONNECTIONS_MIN}, ${MAX_CONNECTIONS_MAX}], got ${max_connections}`
+    );
+  }
+  if (!Number.isFinite(heartbeat_ms) || heartbeat_ms < HEARTBEAT_MS_MIN || heartbeat_ms > HEARTBEAT_MS_MAX) {
+    throw new RangeError(
+      `sse.heartbeatMs must be in [${HEARTBEAT_MS_MIN}, ${HEARTBEAT_MS_MAX}], got ${heartbeat_ms}`
+    );
+  }
+  return {
+    channel: options.channel,
+    maxConnections: max_connections,
+    heartbeatMs: heartbeat_ms
+  };
+}
+var SseConnectionCounter = class {
+  limit;
+  _open = 0;
+  constructor(limit) {
+    this.limit = limit;
+  }
+  /**
+   * Reserve one slot. Returns `true` when accepted (caller must
+   * eventually {@link release} the slot, even on error paths) or
+   * `false` when the cap is already reached.
+   */
+  acquire() {
+    if (this._open >= this.limit) return false;
+    this._open++;
+    return true;
+  }
+  /**
+   * Free a previously-{@link acquire}d slot. Always runs from a
+   * `finally` block in the transport's subscription handler so
+   * crashed handlers don't leak count.
+   */
+  release() {
+    if (this._open > 0) this._open--;
+  }
+  /** Currently-open count. Test/observability hook. */
+  get open() {
+    return this._open;
+  }
+};
+function fireAndForget(op) {
+  return op().catch(() => void 0);
+}
+async function* runSseSubscription(channel, stream_id, accounting, signal, on_cap_exceeded) {
+  if (accounting && !accounting.acquire() && on_cap_exceeded) {
+    on_cap_exceeded();
+  }
+  const pending = [];
+  let resolve_wait = null;
+  const unsubscribe = channel.subscribe(stream_id, (msg) => {
+    pending.push(msg);
+    resolve_wait?.();
+  });
+  const on_abort = () => resolve_wait?.();
+  signal?.addEventListener("abort", on_abort);
+  try {
+    const cached = channel.get_state(stream_id);
+    if (cached !== void 0) {
+      yield { kind: "state", data: cached };
+    }
+    while (!signal?.aborted) {
+      if (pending.length === 0) {
+        await new Promise((resolve) => {
+          resolve_wait = resolve;
+        });
+        if (signal?.aborted) break;
+      }
+      const msg = pending.shift();
+      yield { kind: "patch", data: msg };
+    }
+  } finally {
+    signal?.removeEventListener("abort", on_abort);
+    unsubscribe();
+    accounting?.release();
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_SSE_HEARTBEAT_MS,
+  DEFAULT_SSE_MAX_CONNECTIONS,
   ERROR_MAP,
+  SseConnectionCounter,
+  fireAndForget,
+  resolveSseConfig,
+  runSseSubscription,
   toApiError,
   withIdempotency
 });

package/dist/api/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/api/index.ts","../../src/api/errors.ts","../../src/api/idempotency.ts"],"sourcesContent":["/**\n * @packageDocumentation\n * @module act-http/api\n *\n * Shared utilities for the act-http auto-generated API surfaces.\n * Three concerns that every transport (tRPC, Hono, OpenAPI) has to\n * address — actor extraction, error envelope mapping,\n * `Idempotency-Key` wiring — defined once here and composed by each\n * transport sibling subpath.\n *\n * - {@link ActorExtractor} — the host-supplied closure that resolves\n *   an `Actor` from an incoming request. Auth (JWT, session, API\n *   key) stays in the host; the package only asks for this one\n *   function.\n * - {@link ApiError}, {@link ERROR_MAP}, {@link toApiError} — the\n *   uniform error envelope and the status/code mapping every\n *   transport uses. Cross-transport consistency by construction.\n * - {@link withIdempotency} — the helper that wraps action handlers\n *   in an `Idempotency-Key` claim. Reuses the\n *   `@rotorsoft/act-ops/idempotency` contract that\n *   `@rotorsoft/act-http/receiver` already speaks, so receivers and\n *   generated APIs share one `IdempotencyStore` implementation.\n *\n * Sibling subpaths in the same package consume the utilities here:\n *\n * - `@rotorsoft/act-http/trpc` — tRPC adapter (#843).\n * - `@rotorsoft/act-http/hono` — Hono adapter (#844).\n * - `@rotorsoft/act-http/openapi` — OpenAPI emitter (#845).\n *\n * Existing siblings unrelated to the generated-API work:\n *\n * - `@rotorsoft/act-http/webhook` — outbound POST delivery.\n * - `@rotorsoft/act-http/sse` — incremental state broadcast.\n * - `@rotorsoft/act-http/receiver` — inbound webhook ingestion.\n */\n\nexport type { ActorExtractor } from \"./actor.js\";\nexport {\n  type ApiError,\n  ERROR_MAP,\n  type ErrorMapEntry,\n  toApiError,\n} from \"./errors.js\";\nexport { type IdempotencyResult, withIdempotency } from \"./idempotency.js\";\n","import {\n  ConcurrencyError,\n  InvariantError,\n  NonRetryableError,\n  StreamClosedError,\n  ValidationError,\n} from \"@rotorsoft/act\";\n\n/**\n * Uniform error envelope shipped over the wire by every act-http\n * transport. Hosts get the same shape from REST, tRPC, and OpenAPI —\n * a client that talks to two transports doesn't have to invent two\n * error parsers.\n *\n * - `error` — the framework error name (`\"ValidationError\"`,\n *   `\"InvariantError\"`, …). Stable identifier, safe to switch on.\n * - `detail` — the framework's message text. Human-readable; not\n *   parsed by clients.\n * - `code` — a machine-readable status code from {@link ERROR_MAP}\n *   for clients that prefer enum-style branching over name strings.\n */\nexport type ApiError = {\n  error: string;\n  detail?: string;\n  code?: string;\n};\n\n/**\n * Status + code pair for one known framework error.\n */\nexport type ErrorMapEntry = {\n  status: number;\n  code: string;\n};\n\n/**\n * The single table that maps framework error types to HTTP status\n * codes and machine-readable codes. One table, three consumers\n * (Hono, tRPC, OpenAPI) — cross-transport consistency by\n * construction.\n *\n * Operators wanting different mappings wrap the generated transport\n * rather than mutating this — the consistency is the load-bearing\n * property, not the specific status codes.\n */\nexport const ERROR_MAP = {\n  ValidationError: { status: 422, code: \"VALIDATION\" },\n  InvariantError: { status: 409, code: \"INVARIANT\" },\n  ConcurrencyError: { status: 412, code: \"CONCURRENCY\" },\n  StreamClosedError: { status: 410, code: \"STREAM_CLOSED\" },\n  NonRetryableError: { status: 400, code: \"NON_RETRYABLE\" },\n} as const satisfies Record<string, ErrorMapEntry>;\n\nconst lookup_known = (\n  err: unknown\n): { name: keyof typeof ERROR_MAP } | null => {\n  if (err instanceof ValidationError) return { name: \"ValidationError\" };\n  if (err instanceof InvariantError) return { name: \"InvariantError\" };\n  if (err instanceof ConcurrencyError) return { name: \"ConcurrencyError\" };\n  if (err instanceof StreamClosedError) return { name: \"StreamClosedError\" };\n  if (err instanceof NonRetryableError) return { name: \"NonRetryableError\" };\n  return null;\n};\n\n/**\n * Translate an unknown thrown value into the canonical\n * {@link ApiError} envelope plus HTTP status. Each transport's error\n * boundary calls this once and forwards the result to the wire.\n *\n * Known framework errors map per {@link ERROR_MAP}. Everything else\n * surfaces as a 500 with `code: \"INTERNAL\"`; the `detail` field is\n * populated when the throw was an `Error` instance, omitted\n * otherwise (a thrown string or object doesn't get to leak its\n * payload to the client).\n */\nexport function toApiError(err: unknown): { status: number; body: ApiError } {\n  const known = lookup_known(err);\n  if (known) {\n    const entry = ERROR_MAP[known.name];\n    return {\n      status: entry.status,\n      body: {\n        error: known.name,\n        detail: (err as Error).message,\n        code: entry.code,\n      },\n    };\n  }\n  if (err instanceof Error) {\n    return {\n      status: 500,\n      body: { error: \"InternalError\", detail: err.message, code: \"INTERNAL\" },\n    };\n  }\n  return {\n    status: 500,\n    body: { error: \"InternalError\", code: \"INTERNAL\" },\n  };\n}\n","import type { IdempotencyStore } from \"@rotorsoft/act-ops/idempotency\";\n\n/**\n * Result of a {@link withIdempotency} call.\n *\n * - `{ deduped: false, result }` — the claim was fresh; the handler\n *   ran and produced `result`.\n * - `{ deduped: true }` — the claim was already taken; the handler\n *   was *not* invoked. The caller decides how to respond (typically\n *   a 2xx with no body, matching the receiver-side convention).\n *\n * Note: the contract does not cache the previous response. A\n * duplicate call returns the deduped marker only — replaying the\n * original handler's output would require a response-caching\n * adapter, which is out of scope here. The receiver-side convention\n * (and the convention the generated transports follow) is \"ack the\n * duplicate; do nothing else.\"\n */\nexport type IdempotencyResult<T> =\n  | { deduped: false; result: T }\n  | { deduped: true };\n\n/**\n * Wrap an action handler so the framework honors `Idempotency-Key`\n * dedup. Acquires the key via {@link IdempotencyStore.claim}, runs\n * the handler exactly when the claim was fresh, and skips the\n * handler entirely on a duplicate.\n *\n * Reuses the contract `@rotorsoft/act-ops/idempotency` already\n * defines for the receiver-side `Idempotency-Key` story. A single\n * `IdempotencyStore` implementation covers both halves of the \"Act\n * over the wire\" surface — receiver and generated API.\n */\nexport async function withIdempotency<T>(\n  store: IdempotencyStore,\n  key: string,\n  handler: () => Promise<T>\n): Promise<IdempotencyResult<T>> {\n  const fresh = await store.claim(key);\n  if (!fresh) {\n    return { deduped: true };\n  }\n  return { deduped: false, result: await handler() };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,iBAMO;AAuCA,IAAM,YAAY;AAAA,EACvB,iBAAiB,EAAE,QAAQ,KAAK,MAAM,aAAa;AAAA,EACnD,gBAAgB,EAAE,QAAQ,KAAK,MAAM,YAAY;AAAA,EACjD,kBAAkB,EAAE,QAAQ,KAAK,MAAM,cAAc;AAAA,EACrD,mBAAmB,EAAE,QAAQ,KAAK,MAAM,gBAAgB;AAAA,EACxD,mBAAmB,EAAE,QAAQ,KAAK,MAAM,gBAAgB;AAC1D;AAEA,IAAM,eAAe,CACnB,QAC4C;AAC5C,MAAI,eAAe,2BAAiB,QAAO,EAAE,MAAM,kBAAkB;AACrE,MAAI,eAAe,0BAAgB,QAAO,EAAE,MAAM,iBAAiB;AACnE,MAAI,eAAe,4BAAkB,QAAO,EAAE,MAAM,mBAAmB;AACvE,MAAI,eAAe,6BAAmB,QAAO,EAAE,MAAM,oBAAoB;AACzE,MAAI,eAAe,6BAAmB,QAAO,EAAE,MAAM,oBAAoB;AACzE,SAAO;AACT;AAaO,SAAS,WAAW,KAAkD;AAC3E,QAAM,QAAQ,aAAa,GAAG;AAC9B,MAAI,OAAO;AACT,UAAM,QAAQ,UAAU,MAAM,IAAI;AAClC,WAAO;AAAA,MACL,QAAQ,MAAM;AAAA,MACd,MAAM;AAAA,QACJ,OAAO,MAAM;AAAA,QACb,QAAS,IAAc;AAAA,QACvB,MAAM,MAAM;AAAA,MACd;AAAA,IACF;AAAA,EACF;AACA,MAAI,eAAe,OAAO;AACxB,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,MAAM,EAAE,OAAO,iBAAiB,QAAQ,IAAI,SAAS,MAAM,WAAW;AAAA,IACxE;AAAA,EACF;AACA,SAAO;AAAA,IACL,QAAQ;AAAA,IACR,MAAM,EAAE,OAAO,iBAAiB,MAAM,WAAW;AAAA,EACnD;AACF;;;ACjEA,eAAsB,gBACpB,OACA,KACA,SAC+B;AAC/B,QAAM,QAAQ,MAAM,MAAM,MAAM,GAAG;AACnC,MAAI,CAAC,OAAO;AACV,WAAO,EAAE,SAAS,KAAK;AAAA,EACzB;AACA,SAAO,EAAE,SAAS,OAAO,QAAQ,MAAM,QAAQ,EAAE;AACnD;","names":[]}
+{"version":3,"sources":["../../src/api/index.ts","../../src/api/errors.ts","../../src/api/idempotency.ts","../../src/api/sse-wiring.ts"],"sourcesContent":["/**\n * @packageDocumentation\n * @module act-http/api\n *\n * Shared utilities for the act-http auto-generated API surfaces.\n * Three concerns that every transport (tRPC, Hono, OpenAPI) has to\n * address — actor extraction, error envelope mapping,\n * `Idempotency-Key` wiring — defined once here and composed by each\n * transport sibling subpath.\n *\n * - {@link ActorExtractor} — the host-supplied closure that resolves\n *   an `Actor` from an incoming request. Auth (JWT, session, API\n *   key) stays in the host; the package only asks for this one\n *   function.\n * - {@link ApiError}, {@link ERROR_MAP}, {@link toApiError} — the\n *   uniform error envelope and the status/code mapping every\n *   transport uses. Cross-transport consistency by construction.\n * - {@link withIdempotency} — the helper that wraps action handlers\n *   in an `Idempotency-Key` claim. Reuses the\n *   `@rotorsoft/act-ops/idempotency` contract that\n *   `@rotorsoft/act-http/receiver` already speaks, so receivers and\n *   generated APIs share one `IdempotencyStore` implementation.\n *\n * Sibling subpaths in the same package consume the utilities here:\n *\n * - `@rotorsoft/act-http/trpc` — tRPC adapter (#843).\n * - `@rotorsoft/act-http/hono` — Hono adapter (#844).\n * - `@rotorsoft/act-http/openapi` — OpenAPI emitter (#845).\n *\n * Existing siblings unrelated to the generated-API work:\n *\n * - `@rotorsoft/act-http/webhook` — outbound POST delivery.\n * - `@rotorsoft/act-http/sse` — incremental state broadcast.\n * - `@rotorsoft/act-http/receiver` — inbound webhook ingestion.\n */\n\nexport type { ActorExtractor } from \"./actor.js\";\nexport {\n  type ApiError,\n  ERROR_MAP,\n  type ErrorMapEntry,\n  toApiError,\n} from \"./errors.js\";\nexport { type IdempotencyResult, withIdempotency } from \"./idempotency.js\";\nexport {\n  DEFAULT_SSE_HEARTBEAT_MS,\n  DEFAULT_SSE_MAX_CONNECTIONS,\n  fireAndForget,\n  resolveSseConfig,\n  runSseSubscription,\n  type SseAccounting,\n  type SseConfig,\n  SseConnectionCounter,\n  type SseOptions,\n  type SseSubscriptionFrame,\n} from \"./sse-wiring.js\";\n","import {\n  ConcurrencyError,\n  InvariantError,\n  NonRetryableError,\n  StreamClosedError,\n  ValidationError,\n} from \"@rotorsoft/act\";\n\n/**\n * Uniform error envelope shipped over the wire by every act-http\n * transport. Hosts get the same shape from REST, tRPC, and OpenAPI —\n * a client that talks to two transports doesn't have to invent two\n * error parsers.\n *\n * - `error` — the framework error name (`\"ValidationError\"`,\n *   `\"InvariantError\"`, …). Stable identifier, safe to switch on.\n * - `detail` — the framework's message text. Human-readable; not\n *   parsed by clients.\n * - `code` — a machine-readable status code from {@link ERROR_MAP}\n *   for clients that prefer enum-style branching over name strings.\n */\nexport type ApiError = {\n  error: string;\n  detail?: string;\n  code?: string;\n};\n\n/**\n * Status + code pair for one known framework error.\n */\nexport type ErrorMapEntry = {\n  status: number;\n  code: string;\n};\n\n/**\n * The single table that maps framework error types to HTTP status\n * codes and machine-readable codes. One table, three consumers\n * (Hono, tRPC, OpenAPI) — cross-transport consistency by\n * construction.\n *\n * Operators wanting different mappings wrap the generated transport\n * rather than mutating this — the consistency is the load-bearing\n * property, not the specific status codes.\n */\nexport const ERROR_MAP = {\n  ValidationError: { status: 422, code: \"VALIDATION\" },\n  InvariantError: { status: 409, code: \"INVARIANT\" },\n  ConcurrencyError: { status: 412, code: \"CONCURRENCY\" },\n  StreamClosedError: { status: 410, code: \"STREAM_CLOSED\" },\n  NonRetryableError: { status: 400, code: \"NON_RETRYABLE\" },\n} as const satisfies Record<string, ErrorMapEntry>;\n\nconst lookup_known = (\n  err: unknown\n): { name: keyof typeof ERROR_MAP } | null => {\n  if (err instanceof ValidationError) return { name: \"ValidationError\" };\n  if (err instanceof InvariantError) return { name: \"InvariantError\" };\n  if (err instanceof ConcurrencyError) return { name: \"ConcurrencyError\" };\n  if (err instanceof StreamClosedError) return { name: \"StreamClosedError\" };\n  if (err instanceof NonRetryableError) return { name: \"NonRetryableError\" };\n  return null;\n};\n\n/**\n * Translate an unknown thrown value into the canonical\n * {@link ApiError} envelope plus HTTP status. Each transport's error\n * boundary calls this once and forwards the result to the wire.\n *\n * Known framework errors map per {@link ERROR_MAP}. Everything else\n * surfaces as a 500 with `code: \"INTERNAL\"`; the `detail` field is\n * populated when the throw was an `Error` instance, omitted\n * otherwise (a thrown string or object doesn't get to leak its\n * payload to the client).\n */\nexport function toApiError(err: unknown): { status: number; body: ApiError } {\n  const known = lookup_known(err);\n  if (known) {\n    const entry = ERROR_MAP[known.name];\n    return {\n      status: entry.status,\n      body: {\n        error: known.name,\n        detail: (err as Error).message,\n        code: entry.code,\n      },\n    };\n  }\n  if (err instanceof Error) {\n    return {\n      status: 500,\n      body: { error: \"InternalError\", detail: err.message, code: \"INTERNAL\" },\n    };\n  }\n  return {\n    status: 500,\n    body: { error: \"InternalError\", code: \"INTERNAL\" },\n  };\n}\n","import type { IdempotencyStore } from \"@rotorsoft/act-ops/idempotency\";\n\n/**\n * Result of a {@link withIdempotency} call.\n *\n * - `{ deduped: false, result }` — the claim was fresh; the handler\n *   ran and produced `result`.\n * - `{ deduped: true }` — the claim was already taken; the handler\n *   was *not* invoked. The caller decides how to respond (typically\n *   a 2xx with no body, matching the receiver-side convention).\n *\n * Note: the contract does not cache the previous response. A\n * duplicate call returns the deduped marker only — replaying the\n * original handler's output would require a response-caching\n * adapter, which is out of scope here. The receiver-side convention\n * (and the convention the generated transports follow) is \"ack the\n * duplicate; do nothing else.\"\n */\nexport type IdempotencyResult<T> =\n  | { deduped: false; result: T }\n  | { deduped: true };\n\n/**\n * Wrap an action handler so the framework honors `Idempotency-Key`\n * dedup. Acquires the key via {@link IdempotencyStore.claim}, runs\n * the handler exactly when the claim was fresh, and skips the\n * handler entirely on a duplicate.\n *\n * Reuses the contract `@rotorsoft/act-ops/idempotency` already\n * defines for the receiver-side `Idempotency-Key` story. A single\n * `IdempotencyStore` implementation covers both halves of the \"Act\n * over the wire\" surface — receiver and generated API.\n */\nexport async function withIdempotency<T>(\n  store: IdempotencyStore,\n  key: string,\n  handler: () => Promise<T>\n): Promise<IdempotencyResult<T>> {\n  const fresh = await store.claim(key);\n  if (!fresh) {\n    return { deduped: true };\n  }\n  return { deduped: false, result: await handler() };\n}\n","import type { BroadcastChannel } from \"../sse/broadcast.js\";\nimport type { BroadcastState } from \"../sse/types.js\";\n\n/**\n * SSE wiring options shared by the auto-generated `trpc` and `hono`\n * transports. When supplied, each transport emits one streaming\n * subscription per registered state name, all reading from the same\n * host-supplied {@link BroadcastChannel}.\n *\n * The host owns publication: every `app.do(...)` call site must\n * forward the resulting snapshots to `channel.publish(...)` for\n * subscribers to see updates. The framework deliberately doesn't\n * auto-publish because the derived state usually needs app-specific\n * overlays (presence, computed fields) that only the host can supply.\n *\n * Defaults are sized for typical business-app dashboards (dozens to\n * hundreds of human viewers per process). Both numeric knobs are\n * validated at transport-function construction; out-of-range values\n * throw `RangeError` immediately so misconfiguration surfaces at\n * startup instead of at first connection.\n */\nexport type SseOptions = {\n  /**\n   * The {@link BroadcastChannel} the generator's subscriptions hook\n   * into. Host owns its lifecycle; the generator does not construct\n   * one for you because the channel's `<S>` shape is app-specific and\n   * passing it in keeps the type chain typed end-to-end at the host.\n   */\n  // biome-ignore lint/suspicious/noExplicitAny: the channel's BroadcastState shape is opaque to the generator — narrowing it would force every state into one structural bound that doesn't fit real apps\n  readonly channel: BroadcastChannel<any>;\n  /**\n   * Hard cap on concurrent open subscriptions per generator\n   * instance. The 501st simultaneous open returns `503` (Hono) or\n   * throws `TOO_MANY_REQUESTS` (tRPC) — never a silent stall.\n   *\n   * Default `500`. Validated range `[1, 10_000]`. Above 10k the\n   * framework refuses to construct: at that point the FD ceiling\n   * and per-connection memory force horizontal scaling regardless\n   * of tuning, so the right move is sticky LB + per-process cap,\n   * not a higher single-process limit.\n   */\n  readonly maxConnections?: number;\n  /**\n   * Keep-alive cadence in milliseconds. Most reverse proxies idle\n   * connections out after ~60 seconds; the default `30_000` stays\n   * comfortably under.\n   *\n   * Validated range `[15_000, 300_000]`. Under 15 s wastes\n   * bandwidth on a business workload; over 5 min risks proxy drops.\n   */\n  readonly heartbeatMs?: number;\n};\n\n/**\n * Resolved SSE configuration after validation and default expansion.\n * Internal — the resolved values are what every transport actually\n * runs against.\n *\n * @internal\n */\nexport type SseConfig = {\n  readonly channel: BroadcastChannel<BroadcastState>;\n  readonly maxConnections: number;\n  readonly heartbeatMs: number;\n};\n\n/**\n * Default cap on concurrent open subscriptions per generator\n * instance. Sized for typical business-app dashboards (dozens to a\n * few hundred viewers); high enough not to surprise small\n * deployments, low enough not to mask a missing horizontal-scale\n * strategy on big ones.\n */\nexport const DEFAULT_SSE_MAX_CONNECTIONS = 500;\n\n/**\n * Default keep-alive cadence (30 s). Sits comfortably under the\n * 60 s idle timeout most reverse proxies impose.\n */\nexport const DEFAULT_SSE_HEARTBEAT_MS = 30_000;\n\nconst MAX_CONNECTIONS_MIN = 1;\nconst MAX_CONNECTIONS_MAX = 10_000;\nconst HEARTBEAT_MS_MIN = 15_000;\nconst HEARTBEAT_MS_MAX = 300_000;\n\n/**\n * Validate and apply defaults to host-supplied {@link SseOptions}.\n *\n * Throws `RangeError` when either numeric knob is outside its\n * documented range. Pure: same input → same output, no side\n * effects, no I/O. Each transport calls this once at the start of\n * `hono(...)` / `trpc(...)`.\n */\nexport function resolveSseConfig(options: SseOptions): SseConfig {\n  const max_connections = options.maxConnections ?? DEFAULT_SSE_MAX_CONNECTIONS;\n  const heartbeat_ms = options.heartbeatMs ?? DEFAULT_SSE_HEARTBEAT_MS;\n  if (\n    !Number.isFinite(max_connections) ||\n    max_connections < MAX_CONNECTIONS_MIN ||\n    max_connections > MAX_CONNECTIONS_MAX\n  ) {\n    throw new RangeError(\n      `sse.maxConnections must be in [${MAX_CONNECTIONS_MIN}, ${MAX_CONNECTIONS_MAX}], got ${max_connections}`\n    );\n  }\n  if (\n    !Number.isFinite(heartbeat_ms) ||\n    heartbeat_ms < HEARTBEAT_MS_MIN ||\n    heartbeat_ms > HEARTBEAT_MS_MAX\n  ) {\n    throw new RangeError(\n      `sse.heartbeatMs must be in [${HEARTBEAT_MS_MIN}, ${HEARTBEAT_MS_MAX}], got ${heartbeat_ms}`\n    );\n  }\n  return {\n    channel: options.channel,\n    maxConnections: max_connections,\n    heartbeatMs: heartbeat_ms,\n  };\n}\n\n/**\n * Per-generator concurrent-open counter. Constructed once inside\n * `hono(...)` / `trpc(...)` and consulted at every subscription\n * open: failure to acquire means the cap has been hit and the\n * transport reports `503` / `TOO_MANY_REQUESTS` to the caller.\n *\n * The counter is intentionally process-local. SSE doesn't multiplex\n * across processes; operators wanting more than `maxConnections`\n * viewers run multiple processes behind a sticky load balancer.\n */\nexport class SseConnectionCounter {\n  public readonly limit: number;\n  private _open = 0;\n\n  constructor(limit: number) {\n    this.limit = limit;\n  }\n\n  /**\n   * Reserve one slot. Returns `true` when accepted (caller must\n   * eventually {@link release} the slot, even on error paths) or\n   * `false` when the cap is already reached.\n   */\n  acquire(): boolean {\n    if (this._open >= this.limit) return false;\n    this._open++;\n    return true;\n  }\n\n  /**\n   * Free a previously-{@link acquire}d slot. Always runs from a\n   * `finally` block in the transport's subscription handler so\n   * crashed handlers don't leak count.\n   */\n  release(): void {\n    if (this._open > 0) this._open--;\n  }\n\n  /** Currently-open count. Test/observability hook. */\n  get open(): number {\n    return this._open;\n  }\n}\n\n/**\n * Wrap a fire-and-forget Promise-returning operation so its\n * rejection is swallowed in place of leaking an unhandled\n * rejection. Used by the Hono heartbeat tick (the interval callback\n * isn't `await`ed, so its rejection has nowhere to go) and by any\n * other \"best-effort write\" the transports run.\n *\n * Pure: same input → same output, no side effects on the caller.\n * Returns the chained Promise so the caller can also `await`\n * completion if they want to (the Hono heartbeat doesn't).\n */\nexport function fireAndForget<T>(op: () => Promise<T>): Promise<T | undefined> {\n  return op().catch(() => undefined);\n}\n\n/**\n * Frame yielded by the per-state SSE subscription generator. The\n * initial cached state (when present) arrives as `kind: \"state\"`;\n * every subsequent broadcast publication arrives as `kind: \"patch\"`\n * with the channel's `PatchMessage` payload.\n */\nexport type SseSubscriptionFrame<S> =\n  | { readonly kind: \"state\"; readonly data: S }\n  | { readonly kind: \"patch\"; readonly data: unknown };\n\n/**\n * Subscription accounting hook. Implementations have a chance to\n * acquire a slot before the loop starts and to release it once the\n * loop's `finally` block runs — used by the tRPC side to enforce\n * `maxConnections` from inside the generator, where it can throw\n * `TRPCError` cleanly. Hono enforces the cap outside the loop (so a\n * full counter returns `503` *before* streamSSE writes headers), then\n * passes `undefined` here.\n */\nexport type SseAccounting = {\n  acquire(): boolean;\n  release(): void;\n};\n\n/**\n * The shared subscription loop both transports run. Optionally\n * acquires one slot on the supplied {@link SseAccounting}, yields the\n * cached state (when present), then forwards every channel\n * publication as a `kind: \"patch\"` frame until either the consumer\n * breaks (calling `iter.return()`) or the supplied abort signal fires.\n *\n * Exported as the testable seam — the Hono and tRPC sibling\n * generators wrap this so the signal-driven cleanup and counter\n * accounting live in one place.\n */\n// biome-ignore lint/suspicious/noExplicitAny: the channel's BroadcastState shape is opaque to the loop — narrowing it would force every state into one structural bound that doesn't fit real apps\nexport async function* runSseSubscription<S extends { _v: number } = any>(\n  channel: BroadcastChannel<S>,\n  stream_id: string,\n  accounting: SseAccounting | undefined,\n  signal: AbortSignal | undefined,\n  on_cap_exceeded?: () => never\n): AsyncGenerator<SseSubscriptionFrame<S>> {\n  if (accounting && !accounting.acquire() && on_cap_exceeded) {\n    on_cap_exceeded();\n  }\n  const pending: unknown[] = [];\n  let resolve_wait: (() => void) | null = null;\n  const unsubscribe = channel.subscribe(stream_id, (msg) => {\n    pending.push(msg);\n    resolve_wait?.();\n  });\n  const on_abort = () => resolve_wait?.();\n  signal?.addEventListener(\"abort\", on_abort);\n  try {\n    const cached = channel.get_state(stream_id);\n    if (cached !== undefined) {\n      yield { kind: \"state\", data: cached };\n    }\n    while (!signal?.aborted) {\n      if (pending.length === 0) {\n        await new Promise<void>((resolve) => {\n          resolve_wait = resolve;\n        });\n        if (signal?.aborted) break;\n      }\n      const msg = pending.shift();\n      yield { kind: \"patch\", data: msg };\n    }\n  } finally {\n    signal?.removeEventListener(\"abort\", on_abort);\n    unsubscribe();\n    accounting?.release();\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/api/index.js

@@ -1,11 +1,23 @@
 import {
+  DEFAULT_SSE_HEARTBEAT_MS,
+  DEFAULT_SSE_MAX_CONNECTIONS,
   ERROR_MAP,
+  SseConnectionCounter,
+  fireAndForget,
+  resolveSseConfig,
+  runSseSubscription,
   toApiError,
   withIdempotency
-} from "../chunk-Z6FVXDDU.js";
+} from "../chunk-QOHCL5GN.js";
 import "../chunk-PZ5AY32C.js";
 export {
+  DEFAULT_SSE_HEARTBEAT_MS,
+  DEFAULT_SSE_MAX_CONNECTIONS,
   ERROR_MAP,
+  SseConnectionCounter,
+  fireAndForget,
+  resolveSseConfig,
+  runSseSubscription,
   toApiError,
   withIdempotency
 };

package/dist/chunk-QOHCL5GN.js

@@ -0,0 +1,161 @@
+// src/api/errors.ts
+import {
+  ConcurrencyError,
+  InvariantError,
+  NonRetryableError,
+  StreamClosedError,
+  ValidationError
+} from "@rotorsoft/act";
+var ERROR_MAP = {
+  ValidationError: { status: 422, code: "VALIDATION" },
+  InvariantError: { status: 409, code: "INVARIANT" },
+  ConcurrencyError: { status: 412, code: "CONCURRENCY" },
+  StreamClosedError: { status: 410, code: "STREAM_CLOSED" },
+  NonRetryableError: { status: 400, code: "NON_RETRYABLE" }
+};
+var lookup_known = (err) => {
+  if (err instanceof ValidationError) return { name: "ValidationError" };
+  if (err instanceof InvariantError) return { name: "InvariantError" };
+  if (err instanceof ConcurrencyError) return { name: "ConcurrencyError" };
+  if (err instanceof StreamClosedError) return { name: "StreamClosedError" };
+  if (err instanceof NonRetryableError) return { name: "NonRetryableError" };
+  return null;
+};
+function toApiError(err) {
+  const known = lookup_known(err);
+  if (known) {
+    const entry = ERROR_MAP[known.name];
+    return {
+      status: entry.status,
+      body: {
+        error: known.name,
+        detail: err.message,
+        code: entry.code
+      }
+    };
+  }
+  if (err instanceof Error) {
+    return {
+      status: 500,
+      body: { error: "InternalError", detail: err.message, code: "INTERNAL" }
+    };
+  }
+  return {
+    status: 500,
+    body: { error: "InternalError", code: "INTERNAL" }
+  };
+}
+
+// src/api/idempotency.ts
+async function withIdempotency(store, key, handler) {
+  const fresh = await store.claim(key);
+  if (!fresh) {
+    return { deduped: true };
+  }
+  return { deduped: false, result: await handler() };
+}
+
+// src/api/sse-wiring.ts
+var DEFAULT_SSE_MAX_CONNECTIONS = 500;
+var DEFAULT_SSE_HEARTBEAT_MS = 3e4;
+var MAX_CONNECTIONS_MIN = 1;
+var MAX_CONNECTIONS_MAX = 1e4;
+var HEARTBEAT_MS_MIN = 15e3;
+var HEARTBEAT_MS_MAX = 3e5;
+function resolveSseConfig(options) {
+  const max_connections = options.maxConnections ?? DEFAULT_SSE_MAX_CONNECTIONS;
+  const heartbeat_ms = options.heartbeatMs ?? DEFAULT_SSE_HEARTBEAT_MS;
+  if (!Number.isFinite(max_connections) || max_connections < MAX_CONNECTIONS_MIN || max_connections > MAX_CONNECTIONS_MAX) {
+    throw new RangeError(
+      `sse.maxConnections must be in [${MAX_CONNECTIONS_MIN}, ${MAX_CONNECTIONS_MAX}], got ${max_connections}`
+    );
+  }
+  if (!Number.isFinite(heartbeat_ms) || heartbeat_ms < HEARTBEAT_MS_MIN || heartbeat_ms > HEARTBEAT_MS_MAX) {
+    throw new RangeError(
+      `sse.heartbeatMs must be in [${HEARTBEAT_MS_MIN}, ${HEARTBEAT_MS_MAX}], got ${heartbeat_ms}`
+    );
+  }
+  return {
+    channel: options.channel,
+    maxConnections: max_connections,
+    heartbeatMs: heartbeat_ms
+  };
+}
+var SseConnectionCounter = class {
+  limit;
+  _open = 0;
+  constructor(limit) {
+    this.limit = limit;
+  }
+  /**
+   * Reserve one slot. Returns `true` when accepted (caller must
+   * eventually {@link release} the slot, even on error paths) or
+   * `false` when the cap is already reached.
+   */
+  acquire() {
+    if (this._open >= this.limit) return false;
+    this._open++;
+    return true;
+  }
+  /**
+   * Free a previously-{@link acquire}d slot. Always runs from a
+   * `finally` block in the transport's subscription handler so
+   * crashed handlers don't leak count.
+   */
+  release() {
+    if (this._open > 0) this._open--;
+  }
+  /** Currently-open count. Test/observability hook. */
+  get open() {
+    return this._open;
+  }
+};
+function fireAndForget(op) {
+  return op().catch(() => void 0);
+}
+async function* runSseSubscription(channel, stream_id, accounting, signal, on_cap_exceeded) {
+  if (accounting && !accounting.acquire() && on_cap_exceeded) {
+    on_cap_exceeded();
+  }
+  const pending = [];
+  let resolve_wait = null;
+  const unsubscribe = channel.subscribe(stream_id, (msg) => {
+    pending.push(msg);
+    resolve_wait?.();
+  });
+  const on_abort = () => resolve_wait?.();
+  signal?.addEventListener("abort", on_abort);
+  try {
+    const cached = channel.get_state(stream_id);
+    if (cached !== void 0) {
+      yield { kind: "state", data: cached };
+    }
+    while (!signal?.aborted) {
+      if (pending.length === 0) {
+        await new Promise((resolve) => {
+          resolve_wait = resolve;
+        });
+        if (signal?.aborted) break;
+      }
+      const msg = pending.shift();
+      yield { kind: "patch", data: msg };
+    }
+  } finally {
+    signal?.removeEventListener("abort", on_abort);
+    unsubscribe();
+    accounting?.release();
+  }
+}
+
+export {
+  ERROR_MAP,
+  toApiError,
+  withIdempotency,
+  DEFAULT_SSE_MAX_CONNECTIONS,
+  DEFAULT_SSE_HEARTBEAT_MS,
+  resolveSseConfig,
+  SseConnectionCounter,
+  fireAndForget,
+  runSseSubscription
+};
+//# sourceMappingURL=chunk-QOHCL5GN.js.map