@rotorsoft/act-http 1.5.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

@@ -1,8 +1,8 @@
-import type { Act, Actor, Schema, Schemas } from "@rotorsoft/act";
+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;
 };
 /**
@@ -103,7 +120,26 @@ export declare function authenticated(extractor: ActorExtractor): MiddlewareHand
  * @returns A Hono app covering every registered action under
  *   `<basePath>/actions/<name>`.
  */
-export declare function hono(app: Act<Schemas, Schemas, Schemas, Record<string, Schema>>, options: HonoOptions): Hono<{
+/**
+ * Structural shape of the Act surface this generator walks at
+ * runtime — the registry's action-name → owning-state map plus the
+ * `do(...)` dispatch. Letting TApp infer to the caller's concrete
+ * `Act<...>` against this structural bound keeps nested variance
+ * out of the signature and avoids `any` in either direction.
+ *
+ * @internal
+ */
+type ActSurface = {
+    readonly registry: {
+        actions: Record<string, {
+            readonly name: string;
+            readonly actions: Record<string, unknown>;
+        }>;
+    };
+    do(action: string, target: Target, payload: unknown): Promise<unknown>;
+};
+export declare function hono<TApp extends ActSurface = ActSurface>(app: TApp, options: HonoOptions): Hono<{
     Variables: ActMiddlewareVariables;
 }>;
+export {};
 //# sourceMappingURL=index.d.ts.map

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,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAClE,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,wBAAgB,IAAI,CAClB,GAAG,EAAE,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC3D,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/openapi/index.d.ts

@@ -1,63 +1,3 @@
-/**
- * @packageDocumentation
- * @module act-http/openapi
- *
- * OpenAPI subpath for the auto-generated API epic (#835). Walks the
- * registry of a built `Act` once at function call and returns a
- * valid OpenAPI 3.1 document describing the same action surface the
- * Hono sibling at `@rotorsoft/act-http/hono` serves. The doc is
- * suitable for cross-language client codegen (Go, Python, Swift,
- * Kotlin, .NET), for serving over `/openapi.json` alongside a live
- * API, and for the broader OpenAPI tooling ecosystem (Postman,
- * Swagger UI, Redoc, schemathesis, API gateways).
- *
- * Usage:
- *
- * ```ts
- * import { openapi } from "@rotorsoft/act-http/openapi";
- *
- * const doc = openapi(app, {
- *   info: { title: "Wolfdesk API", version: "1.0.0" },
- *   servers: [{ url: "https://api.example.com" }],
- * });
- * // doc: OpenAPIDocument — valid OpenAPI 3.1 object
- * ```
- *
- * **Pure data emit.** No runtime dep on Hono or tRPC. The subpath is
- * consumable standalone for hosts that serve their API some other
- * way (Fastify, Lambda, edge) or that only want the doc for client
- * codegen. The emit walks the registry once at function call; cost
- * is linear in `N actions × M Zod fields each`, single-digit
- * milliseconds for a 100-endpoint registry.
- *
- * **Determinism.** Output is stable across runs given the same
- * registry — entries land in `Object.entries(app.registry.actions)`
- * iteration order, schemas come from the action's Zod definition,
- * and the rest of the doc is fixed content. CI can snapshot the
- * result to catch unintended API surface changes.
- *
- * The same shared utilities at `@rotorsoft/act-http/api` underwrite
- * cross-transport consistency: the `ApiError` envelope is referenced
- * once from `components.schemas`, every error response points at it,
- * and the same shape ships from the tRPC and Hono siblings at
- * runtime. A client speaking the doc and the live REST API sees one
- * envelope per framework error.
- *
- * **The doc describes the Hono surface, not tRPC.** tRPC's URL
- * shape (`POST /trpc/<procedure>`, JSON-RPC-style body framing,
- * batching) doesn't model cleanly as OpenAPI operations — and tRPC
- * consumers already share types directly via `typeof router`, so
- * OpenAPI buys them nothing. The path shape this emitter produces
- * (`POST <basePath>/actions/<name>`) matches the
- * `@rotorsoft/act-http/hono` sibling exactly: same default
- * `basePath`, same request/response shapes, same envelope. If the
- * operator overrides `basePath` on the Hono adapter, they pass the
- * same override here so the doc keeps matching the live routes by
- * construction. tRPC and Hono can run side-by-side at different
- * mount points on the same Act instance; the OpenAPI doc covers
- * the REST half only.
- */
-import type { Act, Schema, Schemas } from "@rotorsoft/act";
 /**
  * Minimal OpenAPI 3.1 document type. The emitter targets the 3.1
  * spec; the type is intentionally a structural subset rather than
@@ -187,5 +127,23 @@ export type OpenAPIComponents = {
  *   empty, or if any `servers[].url` fails URL parsing after
  *   `{variable}` substitution.
  */
-export declare function openapi(app: Act<Schemas, Schemas, Schemas, Record<string, Schema>>, options: OpenAPIOptions): OpenAPIDocument;
+/**
+ * Structural shape of the Act surface this emitter walks. Letting
+ * TApp infer to the caller's concrete `Act<TSchemaReg, ...>` instead
+ * of forcing it to fit a narrow framework-typed upper bound keeps
+ * the caller's variance from leaking — and avoids `any` in the
+ * signature.
+ *
+ * @internal
+ */
+type ActRegistryView = {
+    readonly registry: {
+        actions: Record<string, {
+            readonly name: string;
+            readonly actions: Record<string, unknown>;
+        }>;
+    };
+};
+export declare function openapi<TApp extends ActRegistryView>(app: TApp, options: OpenAPIOptions): OpenAPIDocument;
+export {};
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/openapi/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/openapi/index.ts"],"names":[],"mappings":"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"}

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

@@ -50,9 +50,10 @@
  * transports never sees two error shapes for the same framework
  * error.
  */
-import type { Act, Schema, Schemas } from "@rotorsoft/act";
+import type { Target } from "@rotorsoft/act";
 import type { IdempotencyStore } from "@rotorsoft/act-ops/idempotency";
-import { type ActorExtractor } from "../api/index.js";
+import { type AnyTRPCMiddlewareFunction, type AnyTRPCMutationProcedure, type AnyTRPCRootTypes, type TRPCBuiltRouter } from "@trpc/server";
+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:
@@ -94,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
@@ -126,7 +143,7 @@ export type TrpcOptions<Ctx> = {
  * (typically wrap them as `TRPCError({ code: "UNAUTHORIZED" })`
  * in the extractor body).
  */
-export declare function authenticated(extractor: ActorExtractor): any;
+export declare function authenticated(extractor: ActorExtractor): AnyTRPCMiddlewareFunction;
 /**
  * Build a typed tRPC router from a built `Act` instance.
  *
@@ -164,5 +181,44 @@ export declare function authenticated(extractor: ActorExtractor): any;
  * @returns A tRPC router covering every registered action, grouped
  *   by owning state.
  */
-export declare function trpc<Ctx extends object = object>(app: Act<any, Schemas, Schemas, Record<string, Schema>>, options: TrpcOptions<Ctx>): never;
+/**
+ * Structural shape of the Act surface this generator walks at
+ * runtime — the registry's action-name → owning-state map plus the
+ * `do(...)` dispatch. Letting TApp infer to the caller's concrete
+ * `Act<...>` against this structural bound (instead of forcing it
+ * to fit a narrow framework-typed upper bound) keeps the variance
+ * of nested types like `PatchHandler` from leaking — and avoids
+ * `any` in the signature.
+ *
+ * @internal
+ */
+type ActSurface = {
+    readonly registry: {
+        actions: Record<string, {
+            readonly name: string;
+            readonly actions: Record<string, unknown>;
+        }>;
+    };
+    do(action: string, target: Target, payload: unknown): Promise<unknown>;
+};
+/**
+ * Generated router type — one mutation procedure per action name in
+ * `TApp`'s registry. Mapped over the concrete action keys so
+ * `createTRPCReact<typeof router>()` sees specific procedure names
+ * (`PressKey`, `Clear`, …) instead of a wide `Record<string, ...>`
+ * index signature — which is what trips tRPC React's
+ * "useContext / Provider / useUtils collides" check on widely-typed
+ * routers.
+ *
+ * @internal
+ */
+type GeneratedRouter<TApp> = TRPCBuiltRouter<AnyTRPCRootTypes, TApp extends {
+    registry: {
+        actions: infer TActions;
+    };
+} ? {
+    [K in keyof TActions]: AnyTRPCMutationProcedure;
+} : Record<string, AnyTRPCMutationProcedure>>;
+export declare function trpc<Ctx extends object = object, TApp extends ActSurface = ActSurface>(app: TApp, options: TrpcOptions<Ctx>): GeneratedRouter<TApp>;
+export {};
 //# sourceMappingURL=index.d.ts.map

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,EAAE,GAAG,EAAS,MAAM,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAEvE,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;AAEH,wBAAgB,aAAa,CAAC,SAAS,EAAE,cAAc,GAAG,GAAG,CAW5D;AA+CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,IAAI,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM,EAE9C,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACvD,OAAO,EAAE,WAAW,CAAC,GAAG,CAAC,SAkE1B"}
+{"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
 });