@voltro/protocol 0.65.0 → 0.66.0

package/dist/rest.d.ts

@@ -100,6 +100,8 @@ export declare const bytes: (stream: ReadableStream<Uint8Array> | (() => Readabl
     readonly contentType?: string;
     readonly contentLength?: number;
     readonly contentDisposition?: string;
+    readonly status?: number;
+    readonly headers?: Readonly<Record<string, string | ReadonlyArray<string>>>;
 }) => RestByteResponse;
 
 /**
@@ -280,6 +282,8 @@ declare interface InsertTarget<Input = unknown, Row = unknown, Item = Record<str
 
 export declare const isRestByteResponse: (v: unknown) => v is RestByteResponse;
 
+export declare const isRestResponse: (value: unknown) => value is RestResponse<unknown>;
+
 export declare const isRestStreamResponse: (v: unknown) => v is RestStreamResponse;
 
 /** Extract `:name` path params by aligning the route PATTERN with the request
@@ -289,12 +293,20 @@ export declare const isRestStreamResponse: (v: unknown) => v is RestStreamRespon
  *  empty and every `:param` route 400s on decode. */
 export declare const matchPathParams: (pattern: string, path: string) => Record<string, string>;
 
+/** Ordinary writes deduplicate across reconnects. A connection-side effect
+ * (for example joining a room) must execute once for EACH native connection. */
+declare type MutationIdempotencyScope = 'subject' | 'connection';
+
 declare interface MutationProcedureDescriptor<Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Error extends Schema.Schema.All> {
     readonly kind: 'mutation';
     readonly name: Name;
     readonly input: Input;
     readonly output: Output;
     readonly error: Error;
+    /** Default 'subject': retries deduplicate across connections. 'connection'
+     * re-executes on a new server-owned WebSocket identity and rejects HTTP RPC.
+     * This does not grant access or restore application membership by itself. */
+    readonly idempotencyScope?: MutationIdempotencyScope | undefined;
     /** Declarative target(s) — drives auto-optimistic on the client AND
      *  surfaces which tables this mutation touches (debug, future
      *  query-invalidation analytics). Mutations without a target run
@@ -793,6 +805,11 @@ declare interface QueryProcedureDescriptor<Name extends string, Input extends Sc
  */
 export declare const requireAnyScope: (scopes: ReadonlyArray<string>) => RestGuard;
 
+/** Require a non-anonymous subject on a REST route. Rejected credentials and
+ *  absent credentials are both authentication failures (401), while scope
+ *  guards remain authorization failures (403). */
+export declare const requireAuthenticated: () => RestGuard;
+
 /**
  * Guard that requires the resolved subject to carry `scope`. Anonymous /
  * scope-less subjects are rejected with `403`. The blanket admin scope
@@ -802,6 +819,11 @@ export declare const requireAnyScope: (scopes: ReadonlyArray<string>) => RestGua
  */
 export declare const requireScope: (scope: string) => RestGuard;
 
+export declare const response: <O>(body: O, options?: {
+    readonly status?: number;
+    readonly headers?: Readonly<Record<string, string | ReadonlyArray<string>>>;
+}) => RestResponse<O>;
+
 /** A BINARY streaming response (download/export). The serve layer pipes the
  *  ReadableStream without buffering — a body larger than the heap is fine.
  *  The LAZY thunk form defers opening the source until the response streams. */
@@ -813,8 +835,12 @@ export declare interface RestByteResponse {
         readonly contentDisposition?: string;
     };
     readonly contentType?: string;
+    readonly status?: number;
+    readonly headers?: Readonly<Record<string, string | ReadonlyArray<string>>>;
 }
 
+export declare const restError: (status: number, body: unknown, headers?: Readonly<Record<string, string | ReadonlyArray<string>>>) => RestRouteError;
+
 export declare type RestGuard = (ctx: RestRouteContext) => RestGuardRejection | undefined | Promise<RestGuardRejection | undefined>;
 
 /**
@@ -829,6 +855,17 @@ export declare interface RestGuardRejection {
 
 export declare type RestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
 
+/** A schema-encoded REST body with an application-selected HTTP status and
+ *  response headers. The marker keeps ordinary domain objects unambiguous.
+ *  `output` still validates/encodes `body`; use `Schema.Void` with a 204 when
+ *  the response intentionally has no representation. */
+export declare interface RestResponse<O> {
+    readonly __voltroRestResponse: true;
+    readonly status: number;
+    readonly body: O;
+    readonly headers?: Readonly<Record<string, string | ReadonlyArray<string>>>;
+}
+
 /**
  * Per-call context handed to a REST route handler. Resolved by the serve
  * pipeline: `subject` from the framework's auth resolver, `headers`
@@ -839,10 +876,22 @@ export declare type RestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | '
 export declare interface RestRouteContext {
     readonly subject: Subject;
     readonly headers: Readonly<Record<string, string>>;
+    /** Request metadata and the byte-exact body as received by the HTTP
+     *  transport. JSON routes normally use decoded `input.body`; `rawBody` is
+     *  for signature verification, multipart parsing, and other protocols where
+     *  parsing first would destroy information the handler must authenticate. */
+    readonly method: RestMethod;
+    readonly path: string;
+    readonly query: string;
+    readonly rawBody: Uint8Array;
     /** Framework `DataStore`. Untyped in protocol (same discipline as
      *  `PluginHttpRoute` / `bindDataStore`); cast to the concrete store at
      *  the call site. `undefined` only in unit tests that don't inject one. */
     readonly store: unknown;
+    /** Full framework context for this authenticated request. This keeps custom
+     *  REST handlers on the same capability surface as query/mutation/action
+     *  handlers without creating a protocol-to-runtime package dependency. */
+    readonly app?: unknown;
 }
 
 export declare interface RestRouteDescriptor<I, O> {
@@ -858,7 +907,7 @@ export declare interface RestRouteDescriptor<I, O> {
     /** Output schema. The handler returns the decoded `Type`; the desugar
      *  encodes it to JSON for the `200` response. */
     readonly output: Schema.Schema<O, any, never>;
-    readonly handler: (input: I, ctx: RestRouteContext) => Promise<O> | O;
+    readonly handler: (input: I, ctx: RestRouteContext) => Promise<O | RestResponse<O>> | O | RestResponse<O>;
     readonly summary?: string;
     readonly description?: string;
     readonly example?: RestRouteExample;
@@ -906,6 +955,16 @@ export declare interface RestRouteDescriptor<I, O> {
     readonly etag?: boolean;
 }
 
+/** Intentional non-2xx REST control flow with an application-defined JSON
+ *  error contract. Unlike an arbitrary thrown object this is never reported as
+ *  a server fault, and its body is not rewritten to `{ error: message }`. */
+export declare class RestRouteError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    readonly headers: Readonly<Record<string, string | ReadonlyArray<string>>> | undefined;
+    constructor(status: number, body: unknown, headers?: Readonly<Record<string, string | ReadonlyArray<string>>>);
+}
+
 export declare interface RestRouteExample {
     readonly request?: unknown;
     readonly response?: unknown;
@@ -929,6 +988,8 @@ export declare interface RestServeBindings {
     readonly resolveSubject?: (headers: Readonly<Record<string, string>>) => Subject | Promise<Subject>;
     /** The bound framework DataStore. */
     readonly store?: unknown;
+    /** Build the full per-request app context after authentication. */
+    readonly buildContext?: (subject: Subject, headers: Readonly<Record<string, string>>) => unknown | Promise<unknown>;
     /**
      * HTTP idempotency — when set, a mutating request (POST/PUT/PATCH/DELETE)
      * carrying the `header` is deduplicated: the first call runs + caches its

package/dist/rest.js

@@ -1,39 +1,56 @@
-import { F as e } from "./scopes-C86BDyNJ.js";
-import { a as t, c as n, o as r, s as i, t as a } from "./serverErrorBus-QQgyq6fV.js";
-import { Effect as o, Schema as s } from "effect";
+import { F as e, P as t } from "./scopes-C86BDyNJ.js";
+import { c as n, l as r, o as i, s as a, t as o } from "./serverErrorBus-BTnTpMqj.js";
+import { Effect as s, Schema as c } from "effect";
 //#region src/publicApi.ts
-var c = (e, t) => t.method ?? (e === "query" ? "GET" : "POST"), l = (e, t) => t.path ?? `/${t.version ?? "v1"}/${e.replace(/\./g, "/")}`, u = (e, t, n) => {
+var l = (e, t) => t.method ?? (e === "query" ? "GET" : "POST"), u = (e, t) => t.path ?? `/${t.version ?? "v1"}/${e.replace(/\./g, "/")}`, d = (e, t, n) => {
 	let r = e.publicApi;
 	if (r === void 0) throw Error(`publicApiRoute: descriptor '${e.name}' has no publicApi annotation`);
-	let i = c(e.kind, r), a = l(e.name, r), o = i === "GET" ? "query" : "body", u = s.Struct({ [o]: e.input }), d = (r.scopes ?? []).map((e) => f(e)), p = r.stream === "sse" && e.kind === "query" && n !== void 0, _ = p ? (e, t) => h((r) => n(e[o], t, (e) => {
-		r(g(String(e._tag ?? "message"), e));
+	let i = l(e.kind, r), a = u(e.name, r), o = i === "GET" ? "query" : "body", s = c.Struct({ [o]: e.input }), d = (r.scopes ?? []).map((e) => m(e)), f = r.stream === "sse" && e.kind === "query" && n !== void 0, p = f ? (e, t) => x((r) => n(e[o], t, (e) => {
+		r(S(String(e._tag ?? "message"), e));
 	})) : (e, n) => t(e[o], n);
-	return m({
+	return b({
 		method: i,
 		path: a,
-		input: u,
+		input: s,
 		output: e.output,
-		handler: _,
-		...p ? { streaming: !0 } : {},
+		handler: p,
+		...f ? { streaming: !0 } : {},
 		...d.length > 0 ? { guards: d } : {},
 		...r.summary === void 0 ? {} : { summary: r.summary },
 		...r.description === void 0 ? {} : { description: r.description },
 		...r.deprecated === void 0 ? {} : { deprecated: r.deprecated },
 		...r.sunset === void 0 ? {} : { sunset: r.sunset }
 	});
-}, d = (e) => e.filter((e) => e.descriptor.publicApi !== void 0).map((e) => u(e.descriptor, e.invoke, e.subscribe)).sort((e, t) => e.path.localeCompare(t.path)), f = (e) => (t) => {
+}, f = (e) => e.filter((e) => e.descriptor.publicApi !== void 0).map((e) => d(e.descriptor, e.invoke, e.subscribe)).sort((e, t) => e.path.localeCompare(t.path)), p = () => (e) => {
+	if (e.subject.type === "anonymous") return {
+		status: 401,
+		message: e.subject.credentialRejected ?? "Authentication required"
+	};
+}, m = (e) => (t) => {
 	let n = t.subject.scopes;
 	if (!(n && (n.includes(e) || n.includes("admin:full")))) return {
 		status: 403,
 		message: `Missing required scope: ${e}`
 	};
-}, p = (e) => (t) => {
+}, h = (e) => (t) => {
 	let n = t.subject.scopes;
 	if (!(n && (n.includes("admin:full") || e.some((e) => n.includes(e))))) return {
 		status: 403,
 		message: `Missing required scope: one of ${e.join(", ")}`
 	};
-}, m = (e) => {
+}, g = (e, t = {}) => ({
+	__voltroRestResponse: !0,
+	status: t.status ?? 200,
+	body: e,
+	...t.headers === void 0 ? {} : { headers: t.headers }
+}), _ = (e) => typeof e == "object" && !!e && e.__voltroRestResponse === !0, v = class extends Error {
+	status;
+	body;
+	headers;
+	constructor(e, t, n) {
+		super(`REST ${e}`), this.name = "RestRouteError", this.status = e, this.body = t, this.headers = n;
+	}
+}, y = (e, t, n) => new v(e, t, n), b = (e) => {
 	if (e.version === void 0) return e;
 	if (!/^v\d+$/.test(e.version)) throw Error(`defineRestRoute(${e.method} ${e.path}): version "${e.version}" must be 'v' followed by digits — 'v1', 'v2', …`);
 	if ((/* @__PURE__ */ RegExp("^/v\\d+(/|$)")).test(e.path)) throw Error(`defineRestRoute(${e.method} ${e.path}): the path already starts with a version segment AND declares version: '${e.version}'. Pick one spelling — either bake the version into the path, or declare version: and keep the path bare ('/customers'). Both would mount '/${e.version}${e.path}', which is never what the author meant.`);
@@ -41,37 +58,39 @@ var c = (e, t) => t.method ?? (e === "query" ? "GET" : "POST"), l = (e, t) => t.
 		...e,
 		path: `/${e.version}${e.path}`
 	};
-}, h = (e, t = {}) => ({
+}, x = (e, t = {}) => ({
 	__voltroRestStream: !0,
 	stream: {
 		subscribe: e,
 		...t.keepAliveMs === void 0 ? {} : { keepAliveMs: t.keepAliveMs }
 	}
-}), g = (e, t) => `event: ${e}\n${(typeof t == "string" ? t : JSON.stringify(t)).split("\n").map((e) => `data: ${e}`).join("\n")}\n\n`, _ = (e) => typeof e == "object" && !!e && e.__voltroRestStream === !0, v = (e, t = {}) => ({
+}), S = (e, t) => `event: ${e}\n${(typeof t == "string" ? t : JSON.stringify(t)).split("\n").map((e) => `data: ${e}`).join("\n")}\n\n`, C = (e) => typeof e == "object" && !!e && e.__voltroRestStream === !0, w = (e, t = {}) => ({
 	__voltroRestBytes: !0,
 	byteStream: {
 		stream: e,
 		...t.contentLength === void 0 ? {} : { contentLength: t.contentLength },
 		...t.contentDisposition === void 0 ? {} : { contentDisposition: t.contentDisposition }
 	},
-	...t.contentType === void 0 ? {} : { contentType: t.contentType }
-}), y = (e) => typeof e == "object" && !!e && e.__voltroRestBytes === !0, b = async (e) => {
+	...t.contentType === void 0 ? {} : { contentType: t.contentType },
+	...t.status === void 0 ? {} : { status: t.status },
+	...t.headers === void 0 ? {} : { headers: t.headers }
+}), T = (e) => typeof e == "object" && !!e && e.__voltroRestBytes === !0, E = async (e) => {
 	let t = await globalThis.crypto.subtle.digest("SHA-1", new TextEncoder().encode(e));
 	return [...new Uint8Array(t)].map((e) => e.toString(16).padStart(2, "0")).join("");
-}, x = (e, t, n) => ({
+}, D = (e, t, n) => ({
 	status: e,
 	contentType: "application/json; charset=utf-8",
 	body: JSON.stringify(t),
 	...n ? { headers: n } : {}
-}), S = (e) => {
+}), O = (e) => {
 	if (e.length === 0) return;
 	let t = new TextDecoder().decode(e);
 	if (t.trim() !== "") return JSON.parse(t);
-}, C = (e) => {
+}, k = (e) => {
 	let t = {};
 	for (let [n, r] of new URLSearchParams(e)) t[n] = r;
 	return t;
-}, w = (e, t) => {
+}, A = (e, t) => {
 	let n = e.split("/").filter((e) => e.length > 0), r = t.split("/").filter((e) => e.length > 0), i = {};
 	for (let e = 0; e < n.length; e++) {
 		let t = n[e];
@@ -85,124 +104,153 @@ var c = (e, t) => t.method ?? (e === "query" ? "GET" : "POST"), l = (e, t) => t.
 		}
 	}
 	return i;
-}, T = (e, t) => ({
-	query: C(e.query),
+}, j = (e, t) => ({
+	query: k(e.query),
 	params: t,
-	body: S(e.rawBody)
-}), E = /* @__PURE__ */ new Set([
+	body: O(e.rawBody)
+}), M = /* @__PURE__ */ new Set([
 	"POST",
 	"PUT",
 	"PATCH",
 	"DELETE"
-]), D = (c, l) => {
-	let u = c.input ? s.decodeUnknown(c.input) : void 0, d = s.encode(c.output), f = {};
-	return c.deprecated !== void 0 && (f.Deprecation = "true"), c.sunset !== void 0 && (f.Sunset = c.sunset), {
+]), N = (l, u) => {
+	let d = l.input ? c.decodeUnknown(l.input) : void 0, f = c.encode(l.output), p = {}, m = (e) => e.replace(/\/$/, "").split("/").length, h = m(l.path);
+	return l.deprecated !== void 0 && (p.Deprecation = "true"), l.sunset !== void 0 && (p.Sunset = l.sunset), {
 		method: "*",
-		path: c.path,
-		...c.maxBodyBytes === void 0 ? {} : { maxBodyBytes: c.maxBodyBytes },
-		handle: async (s) => {
-			let p = s.method.toUpperCase();
-			if (!(p === c.method || p === "HEAD" && c.method === "GET")) return x(405, {
+		path: l.path,
+		...l.maxBodyBytes === void 0 ? {} : { maxBodyBytes: l.maxBodyBytes },
+		handle: async (c) => {
+			if (!l.path.endsWith("/*") && m(c.path) !== h) return D(404, { error: "Not Found" }, p);
+			let y = c.method.toUpperCase();
+			if (!(y === l.method || y === "HEAD" && l.method === "GET")) return D(405, {
 				error: "Method Not Allowed",
-				allow: c.method
+				allow: l.method
 			}, {
-				...f,
-				Allow: c.method
+				...p,
+				Allow: l.method
 			});
-			if (c.sunset !== void 0) {
-				let e = Date.parse(c.sunset);
-				if (!Number.isNaN(e) && Date.now() >= e) return x(410, {
+			if (l.sunset !== void 0) {
+				let e = Date.parse(l.sunset);
+				if (!Number.isNaN(e) && Date.now() >= e) return D(410, {
 					error: "Gone",
-					...c.version === void 0 ? {} : { version: c.version },
-					...c.deprecated === void 0 ? {} : { replacement: c.deprecated }
-				}, f);
+					...l.version === void 0 ? {} : { version: l.version },
+					...l.deprecated === void 0 ? {} : { replacement: l.deprecated }
+				}, p);
 			}
-			let m;
-			if (u) {
-				let e = T(s, w(c.path, s.path)), t = await o.runPromise(u(e).pipe(o.map((e) => ({
+			let b;
+			if (d) {
+				let e = j(c, A(l.path, c.path)), t = await s.runPromise(d(e).pipe(s.map((e) => ({
 					ok: !0,
 					value: e
-				})), o.catchAll((e) => o.succeed({
+				})), s.catchAll((e) => s.succeed({
 					ok: !1,
 					cause: e
 				}))));
-				if (!t.ok) return x(400, {
+				if (!t.ok) return D(400, {
 					error: "Invalid request",
 					detail: String(t.cause)
-				}, f);
-				m = t.value;
+				}, p);
+				b = t.value;
+			}
+			let x;
+			try {
+				x = u.resolveSubject ? await u.resolveSubject(c.headers) : e(c.headers["x-tenant"] ?? null);
+			} catch (e) {
+				if (e instanceof t || typeof e == "object" && e && e._tag === "Unauthenticated") {
+					let t = e.reason;
+					return D(401, { error: t ?? "Authentication required" }, p);
+				}
+				throw e;
 			}
-			let h = l.resolveSubject ? await l.resolveSubject(s.headers) : e(s.headers["x-tenant"] ?? null), g = {
-				subject: h,
-				headers: s.headers,
-				store: l.store
+			let S = u.buildContext ? await u.buildContext(x, c.headers) : void 0, w = typeof S == "object" && S && "store" in S ? S.store : u.store, O = {
+				subject: x,
+				headers: c.headers,
+				store: w,
+				method: y,
+				path: c.path,
+				query: c.query,
+				rawBody: c.rawBody,
+				...S === void 0 ? {} : { app: S }
 			};
-			if (c.guards) for (let e of c.guards) {
-				let t = await e(g);
-				if (t) return x(t.status, { error: t.message }, f);
+			if (l.guards) for (let e of l.guards) {
+				let t = await e(O);
+				if (t) return D(t.status, { error: t.message }, p);
 			}
-			let v = l.idempotency, S = v && E.has(c.method) ? s.headers[v.header.toLowerCase()] : void 0, C = v && S ? n(h.tenantId, c.method, c.path) : "";
-			if (v && S) {
-				let e = await t(v.store, C, S, v.ttlMs, Date.now());
-				if (e.kind === "replay") return x(e.response.status, e.response.body, {
-					...f,
+			let k = u.idempotency, N = k && M.has(l.method) ? c.headers[k.header.toLowerCase()] : void 0, P = k && N ? r(x.tenantId, l.method, l.path) : "";
+			if (k && N) {
+				let e = await i(k.store, P, N, k.ttlMs, Date.now());
+				if (e.kind === "replay") return D(e.response.status, e.response.body, {
+					...p,
 					"Idempotency-Replayed": "true"
 				});
-				if (e.kind === "conflict") return x(409, { error: "A request with this Idempotency-Key is already being processed" }, f);
+				if (e.kind === "conflict") return D(409, { error: "A request with this Idempotency-Key is already being processed" }, p);
 			}
 			try {
-				let e = await c.handler(m, g);
-				if (_(e) || y(e)) return v && S && await r(v.store, C, S), y(e) ? {
-					status: 200,
-					headers: f,
+				let e = await l.handler(b, O);
+				if (C(e) || T(e)) return k && N && await a(k.store, P, N), T(e) ? {
+					status: e.status ?? 200,
+					headers: {
+						...p,
+						...e.headers
+					},
 					byteStream: e.byteStream,
 					...e.contentType === void 0 ? {} : { contentType: e.contentType }
 				} : {
 					status: 200,
-					headers: f,
+					headers: p,
 					stream: e.stream
 				};
-				let t = await o.runPromise(d(e));
-				if (v && S && await i(v.store, C, S, {
-					status: 200,
-					body: t
-				}, Date.now()), c.etag === !0 && c.method === "GET") {
-					let e = `W/"${await b(JSON.stringify(t))}"`, n = s.headers["if-none-match"];
+				let t = _(e) ? e : g(e), r = await s.runPromise(f(t.body)), i = {
+					...p,
+					...t.headers
+				};
+				if (k && N && await n(k.store, P, N, {
+					status: t.status,
+					body: r
+				}, Date.now()), l.etag === !0 && l.method === "GET") {
+					let e = `W/"${await E(JSON.stringify(r))}"`, n = c.headers["if-none-match"];
 					return n !== void 0 && n.split(",").some((t) => t.trim() === e) ? {
 						status: 304,
 						headers: {
-							...f,
+							...p,
 							ETag: e
 						}
-					} : x(200, t, {
-						...f,
+					} : D(t.status, r, {
+						...i,
 						ETag: e
 					});
 				}
-				return x(200, t, f);
+				return t.status === 204 || t.status === 304 ? {
+					status: t.status,
+					headers: i
+				} : D(t.status, r, i);
 			} catch (e) {
-				if (v && S && await r(v.store, C, S), typeof e == "object" && e && typeof e.status == "number") {
+				if (k && N && await a(k.store, P, N), e instanceof v) return D(e.status, e.body, {
+					...p,
+					...e.headers
+				});
+				if (typeof e == "object" && e && typeof e.status == "number") {
 					let t = e;
-					return x(t.status, { error: t.message ?? "Error" }, f);
+					return D(t.status, { error: t.message ?? "Error" }, p);
 				}
-				return a({
+				return o({
 					error: e,
 					source: "rest",
-					name: `${c.method} ${c.path}`,
+					name: `${l.method} ${l.path}`,
 					fields: { status: 500 }
-				}), x(500, { error: "Internal Server Error" }, f);
+				}), D(500, { error: "Internal Server Error" }, p);
 			}
 		}
 	};
-}, O = (e, t = {}) => {
+}, P = (e, t = {}) => {
 	if (t.idempotency !== void 0) {
-		for (let t of e) if (t.streaming === !0 && E.has(t.method)) throw Error(`REST route ${t.method} ${t.path} declares \`streaming: true\` on a method the idempotency binding claims (${[...E].join("/")}). A stream cannot complete an idempotency claim — there is no replayable body to cache — so a retried request would 409 until the claim's TTL. Either serve the stream on GET, or scope the idempotency binding away from this app's streaming routes.`);
+		for (let t of e) if (t.streaming === !0 && M.has(t.method)) throw Error(`REST route ${t.method} ${t.path} declares \`streaming: true\` on a method the idempotency binding claims (${[...M].join("/")}). A stream cannot complete an idempotency claim — there is no replayable body to cache — so a retried request would 409 until the claim's TTL. Either serve the stream on GET, or scope the idempotency binding away from this app's streaming routes.`);
 	}
-	return e.map((e) => D(e, t));
-}, k = async (e, t) => {
+	return e.map((e) => N(e, t));
+}, F = async (e, t) => {
 	let n = await e[0].handle(t);
 	for (let r = 1; r < e.length && n.status === 405; r++) n = await e[r].handle(t);
 	return n;
 };
 //#endregion
-export { v as bytes, d as collectPublicApiRoutes, m as defineRestRoute, c as derivePublicMethod, l as derivePublicPath, k as dispatchSharedPath, y as isRestByteResponse, _ as isRestStreamResponse, w as matchPathParams, u as publicApiRoute, p as requireAnyScope, f as requireScope, O as restRoutesToHttpRoutes, h as sse, g as sseFrame };
+export { v as RestRouteError, w as bytes, f as collectPublicApiRoutes, b as defineRestRoute, l as derivePublicMethod, u as derivePublicPath, F as dispatchSharedPath, T as isRestByteResponse, _ as isRestResponse, C as isRestStreamResponse, A as matchPathParams, d as publicApiRoute, h as requireAnyScope, p as requireAuthenticated, m as requireScope, g as response, y as restError, P as restRoutesToHttpRoutes, x as sse, S as sseFrame };

package/dist/{serverErrorBus-QQgyq6fV.js → serverErrorBus-BTnTpMqj.js}

@@ -1,12 +1,21 @@
 import { Schema as e } from "effect";
 //#region src/idempotency.ts
-var t = (e, t, n) => `${e ?? "(global)"}|${t.toUpperCase()}|${n}`, n = (e, t, n) => `${e ?? "(global)"}|${t ?? "(anon)"}|WS|${n}`, r = async (e, t, n, r, i) => {
+var t = (e, t, n) => `${e ?? "(global)"}|${t.toUpperCase()}|${n}`, n = (e, t, n, r) => r === void 0 ? `${e ?? "(global)"}|${t ?? "(anon)"}|WS|${n}` : `WS-connection:${JSON.stringify([
+	e ?? null,
+	t ?? null,
+	n,
+	r
+])}`, r = class extends e.TaggedError()("MutationConnectionRequired", { traceId: e.String }) {
+	get message() {
+		return "this mutation requires a live native WebSocket connection";
+	}
+}, i = async (e, t, n, r, i) => {
 	let a = await e.claim(t, n, i, r);
 	return a === "claimed" ? { kind: "fresh" } : a.status === "completed" && a.response ? {
 		kind: "replay",
 		response: a.response
 	} : { kind: "conflict" };
-}, i = (e, t, n, r, i) => e.complete(t, n, r, i), a = (e, t, n) => e.release(t, n), o = () => {
+}, a = (e, t, n, r, i) => e.complete(t, n, r, i), o = (e, t, n) => e.release(t, n), s = () => {
 	let e = /* @__PURE__ */ new Map(), t = (e, t) => `${e}\u0000${t}`;
 	return {
 		get: async (n, r) => e.get(t(n, r)) ?? null,
@@ -33,19 +42,19 @@ var t = (e, t, n) => `${e ?? "(global)"}|${t.toUpperCase()}|${n}`, n = (e, t, n)
 			e.delete(t(n, r));
 		}
 	};
-}, s = class extends e.TaggedError()("MutationInFlight", {
+}, c = class extends e.TaggedError()("MutationInFlight", {
 	traceId: e.String,
 	retryAfterMs: e.Number
 }) {
 	get message() {
 		return `a request with this idempotency key is still in flight — replay the same key after ${this.retryAfterMs}ms`;
 	}
-}, c = 1e3, l = /* @__PURE__ */ new Set(), u = (e) => {
-	for (let t of l) try {
+}, l = 1e3, u = /* @__PURE__ */ new Set(), d = (e) => {
+	for (let t of u) try {
 		t(e);
 	} catch {}
-}, d = (e) => (l.add(e), () => {
-	l.delete(e);
+}, f = (e) => (u.add(e), () => {
+	u.delete(e);
 });
 //#endregion
-export { r as a, t as c, s as i, o as l, d as n, a as o, c as r, i as s, u as t, n as u };
+export { c as a, a as c, n as d, r as i, t as l, f as n, i as o, l as r, o as s, d as t, s as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/protocol",
-  "version": "0.65.0",
+  "version": "0.66.0",
   "description": "The Voltro wire + plugin contract — defineQuery/Mutation/Action/Stream, definePlugin, sessions / JWT / API-keys, and the RPC protocol.",
   "keywords": [
     "voltro",
@@ -59,8 +59,8 @@
   },
   "dependencies": {
     "@effect/sql": "^0.52.0",
-    "@voltro/database": "0.65.0",
-    "@voltro/logger": "0.65.0",
+    "@voltro/database": "0.66.0",
+    "@voltro/logger": "0.66.0",
     "jose": "^6.2.8"
   },
   "peerDependencies": {