@voltro/protocol 0.85.0 → 0.87.0

package/dist/procedure.js

@@ -0,0 +1,280 @@
+import { subscriptionEvent as e } from "./subscriptionEvent.js";
+import { RequestedTenantRefused as t } from "./tenantSelection.js";
+import { Unauthenticated as n } from "./auth.js";
+import { NoSuchResource as r, ScopeError as i, declaresResourceGuard as a, isOpenAccess as o, openAccessSpec as s, serviceAccessSpec as c, upgradedGuardShapeError as l } from "./scopes.js";
+import { strictInput as u } from "./strictInput.js";
+import { BusinessRuleViolation as d } from "./businessRule.js";
+import { MutationConnectionRequired as f, MutationIdempotencyRefused as p, MutationInFlight as m } from "./idempotency.js";
+import { ValidationError as h, ValidationErrors as g } from "./validation.js";
+import { ApprovalErrors as _ } from "./approval.js";
+import { normalizeSource as v } from "./reactivityChannel.js";
+import { captureOptionalQuerySources as y } from "./queryOptionalSources.js";
+import { Schema as b } from "effect";
+import { Rpc as x } from "effect/rpc";
+import { VersionConflict as S } from "@voltro/database/wire";
+//#region src/procedure.ts
+var C = (e) => e.internal !== !0, w = (e) => e.service === void 0 ? "client" : "service", T = (e) => C(e) && e.service === void 0, E = (e) => C(e) && e.service !== void 0, D = /^[a-z][a-z0-9-]{0,55}$/i, O = (e) => {
+	if (A(e), k(e), e.undo !== void 0 && (e.undo === null || e.undo.capture !== !1 || typeof e.undo.reason != "string" || e.undo.reason.trim() === "")) throw Error(`${e.name}: undo requires capture: false and a non-empty reason`);
+	if (e.idempotencyScope !== void 0 && e.idempotencyScope !== "subject" && e.idempotencyScope !== "connection") throw Error(`${e.name}: idempotencyScope must be 'subject' or 'connection'`);
+	let t = e.serialize;
+	if (t !== void 0) {
+		if (typeof t.key != "function") throw Error(`${e.name}: serialize.key must be a function of the input`);
+		if (t.maxPending !== void 0 && (!Number.isSafeInteger(t.maxPending) || t.maxPending < 1)) throw Error(`${e.name}: serialize.maxPending must be a positive integer`);
+	}
+	if (e.idempotencyScope === "connection" && (e.internal === !0 || e.publicApi !== void 0 || e.exposeAsTool !== void 0)) throw Error(`${e.name}: connection-scoped mutations require the native WebSocket RPC surface; internal, publicApi and exposeAsTool cannot establish its connection state`);
+	if (Array.isArray(e.guards) && e.guards.length === 0) throw Error(`${e.name}: \`guards: []\` is empty, so it enforces nothing — but it reads\n  at the call site as if this procedure were protected. Omit the field for an
+  unguarded procedure, or list the scopes required to call it.`);
+	let n = typeof e.source == "string" ? [e.source] : Array.isArray(e.source) ? e.source : void 0;
+	if (n !== void 0 && (n.length === 0 || n.some((e) => String(e).trim() === ""))) throw Error(`${e.name}: \`source\` is empty, so this query declares reactivity and\n  subscribes to nothing — it serves one snapshot and never updates again,
+  which is indistinguishable from "nothing changed". Name the table(s) it
+  reads, or omit \`source\` for a non-reactive query.`);
+	if (e.internal !== !0) return e;
+	if (e.openAccess !== void 0) throw Error(`${e.name}: \`internal: true\` cannot be combined with \`openAccess\`.\n  \`internal\` takes the procedure OFF the wire, and \`openAccess\` declares who may
+  call it there — together they describe a decision about a surface that does not
+  exist. Drop \`openAccess\` (an internal procedure needs no wire decision), or drop
+  \`internal: true\` if the procedure really is meant to be callable.`);
+	if (e.overridesPlugin === !0) throw Error(`${e.name}: \`internal: true\` cannot be combined with \`overridesPlugin\`.\n  The override REMOVES the plugin route, and an internal procedure is not
+  wire-reachable — so the plugin's route would vanish with nothing callable
+  in its place, and callers would get a 404 for something that used to work.`);
+	let r = [e.publicApi === void 0 ? void 0 : "publicApi", e.exposeAsTool === void 0 ? void 0 : "exposeAsTool"].filter((e) => e !== void 0);
+	if (r.length === 0) return e;
+	throw Error(`${e.name}: \`internal: true\` cannot be combined with ${r.map((e) => `\`${e}\``).join(" or ")}. \`internal\` takes the procedure OFF the wire; those put it back ON a different one (${r.includes("publicApi") ? "a REST route" : "an agent tool"}), and that surface is projected without consulting the flag — so the procedure would be unreachable from your client and reachable from the internet. Drop \`internal: true\` if the wider surface is intended, or remove the ${r.join(" / ")} annotation if it is not.`);
+}, k = (e) => {
+	let t = e.service;
+	if (t === void 0) return;
+	let n = t.callers;
+	if (!Array.isArray(n) || n.length === 0) throw Error(`${e.name}: \`service.callers\` is empty, so NO app may call this procedure —\n  and no browser either. Name the calling app(s), e.g. \`service: { callers: ['worker'] }\`,
+  or drop \`service:\` if the procedure is meant for this app's own clients.`);
+	let r = n.filter((e) => typeof e != "string" || !D.test(e));
+	if (r.length > 0) throw Error(`${e.name}: \`service.callers\` holds ${r.map((e) => JSON.stringify(e)).join(", ")} — a caller is an\n  app name (letters, digits, dashes; starting with a letter; at most 56 characters), the same name this app
+  lists in \`serviceCallers\` and the caller's credential resolves to.`);
+	if (new Set(n).size !== n.length) throw Error(`${e.name}: \`service.callers\` lists the same app twice`);
+	let i = [
+		e.internal === !0 ? "`internal: true` (it removes the wire surface a service calls over)" : void 0,
+		e.publicApi === void 0 ? void 0 : "`publicApi` (a REST route is for callers that are not the listed apps)",
+		e.exposeAsTool === void 0 ? void 0 : "`exposeAsTool` (an agent tool is not one of the listed apps)",
+		e.requiresApproval === void 0 ? void 0 : "`requiresApproval` (a second HUMAN cannot approve a machine call)",
+		e.overridesPlugin === !0 ? "`overridesPlugin` (a plugin route is a client surface; replacing it with a service-only one breaks its clients)" : void 0,
+		e.idempotencyScope === "connection" ? "`idempotencyScope: 'connection'` (a service call dedups per service, across reconnects)" : void 0
+	].filter((e) => e !== void 0);
+	if (i.length !== 0) throw Error(`${e.name}: \`service:\` cannot be combined with ${i.join("; ")}.\n  A service procedure is callable only by the listed apps of this project, over the
+  socket, with their service credential. Drop the other field, or drop \`service:\`.`);
+}, A = (e) => {
+	let t = e.requiresApproval;
+	if (t !== void 0) {
+		if (!Array.isArray(t.approvers) || t.approvers.length === 0) throw Error(`${e.name}: \`requiresApproval.approvers\` is empty, so NOBODY can approve this\n  procedure and every call would park forever. Name the scope(s) an approver must hold
+  — e.g. \`approvers: [{ scope: 'invoices:approve' }]\`.`);
+		if (e.openAccess !== void 0) throw Error(`${e.name}: \`requiresApproval\` cannot be combined with \`openAccess\`.\n  The self-approval refusal compares subject ids, and an unauthenticated caller has
+  none — so on an open procedure every anonymous caller would count as a DIFFERENT
+  human from every other, and the second-pair-of-eyes control would enforce nothing.
+  Give the procedure a \`guards:\` decision, or drop \`requiresApproval\`.`);
+	}
+}, ee = () => ({ upgraded: !0 }), te = (e) => e.action !== void 0 && e.resourceType !== void 0, ne = (e) => e.authenticated === !0, j = (e) => e.upgraded === !0, M = (e) => e.openAccess !== void 0 || e.guards !== void 0 && e.guards.length > 0, N = (e, t, n, r) => {
+	for (let e of t ?? []) {
+		let t = l(e);
+		if (t) throw t;
+	}
+	if (r !== void 0) {
+		if (n !== void 0 || t !== void 0 && t.length > 0) throw Error(`${e}: \`service:\` is an access decision of its own — only the listed apps may\n  call this procedure — so it cannot sit beside \`guards:\` or \`openAccess:\`. A service
+  holds no scopes, and no user may call a service procedure. Keep exactly one.`);
+		return Array.isArray(r.callers) ? [c(r.callers)] : void 0;
+	}
+	if (n === void 0) return t;
+	if (n.trim() === "") throw Error(`${e}: \`openAccess\` needs a REASON, not an empty string. It is the sentence a\n  reviewer reads to decide whether this procedure should really be callable
+  without an authorization check — e.g. \`openAccess: 'public pricing, no caller data'\`.`);
+	if (t !== void 0 && t.length > 0) throw Error(`${e}: \`openAccess\` and \`guards\` are two different access decisions, so\n  declaring both says the procedure is protected AND open. Keep the guards if a
+  caller must hold a scope; drop them if anyone may call it.`);
+	return [s(n.trim())];
+}, P = (e) => {
+	let t = v(e.source), n = y(e.name, t, e.optionalSource);
+	return O({
+		kind: "query",
+		name: e.name,
+		input: e.input,
+		output: e.output,
+		error: e.error ?? b.Never,
+		source: t,
+		...n === void 0 ? {} : { optionalSource: n },
+		cache: e.cache,
+		guards: N(e.name, e.guards, e.openAccess, e.service),
+		openAccess: e.openAccess,
+		service: e.service === void 0 ? void 0 : { callers: Array.isArray(e.service.callers) ? [...e.service.callers] : e.service.callers },
+		publicApi: e.publicApi,
+		exposeAsTool: e.exposeAsTool,
+		internal: e.internal,
+		overridesPlugin: e.overridesPlugin
+	});
+}, F = (e) => O({
+	kind: "mutation",
+	name: e.name,
+	input: e.input,
+	output: e.output,
+	error: e.error ?? b.Never,
+	...e.idempotencyScope === void 0 ? {} : { idempotencyScope: e.idempotencyScope },
+	...e.serialize === void 0 ? {} : { serialize: e.serialize },
+	...e.undo === void 0 ? {} : { undo: e.undo },
+	target: e.target,
+	guards: N(e.name, e.guards, e.openAccess, e.service),
+	openAccess: e.openAccess,
+	service: e.service === void 0 ? void 0 : { callers: Array.isArray(e.service.callers) ? [...e.service.callers] : e.service.callers },
+	publicApi: e.publicApi,
+	exposeAsTool: e.exposeAsTool,
+	requiresApproval: e.requiresApproval,
+	internal: e.internal,
+	overridesPlugin: e.overridesPlugin
+}), I = (e) => O({
+	kind: "action",
+	name: e.name,
+	input: e.input,
+	output: e.output,
+	error: e.error ?? b.Never,
+	guards: N(e.name, e.guards, e.openAccess, e.service),
+	openAccess: e.openAccess,
+	service: e.service === void 0 ? void 0 : { callers: Array.isArray(e.service.callers) ? [...e.service.callers] : e.service.callers },
+	source: e.source,
+	target: e.target,
+	publicApi: e.publicApi,
+	exposeAsTool: e.exposeAsTool,
+	requiresApproval: e.requiresApproval,
+	internal: e.internal,
+	overridesPlugin: e.overridesPlugin
+}), L = (e) => O({
+	kind: "stream",
+	name: e.name,
+	input: e.input,
+	element: e.element,
+	error: e.error ?? b.Never,
+	internal: e.internal,
+	overridesPlugin: e.overridesPlugin,
+	guards: N(e.name, e.guards, e.openAccess),
+	openAccess: e.openAccess
+}), R = (e, t) => t && t.length > 0 ? b.Union([e, ...new Set(t)]) : e, z = (e) => e !== void 0 && e.some((e) => !o(e)), B = (e) => b.Union([
+	e,
+	i,
+	n,
+	t
+]), V = (e) => b.Union([e, d]), H = (e) => b.Union([
+	e,
+	h,
+	g
+]), U = (e, t) => t === void 0 ? e : b.Union([e, _]), W = (e, t) => a(t) ? b.Union([e, r]) : e, G = (e, t, n) => R(K(e, t), n), K = (e, t) => {
+	let n = W(B(e.error), e.guards);
+	if (t === "stream" || t === "query") return n;
+	let r = t === "mutation" ? b.Union([
+		V(n),
+		m,
+		p,
+		S
+	]) : b.Union([
+		n,
+		m,
+		p
+	]);
+	return U(H(t === "mutation" && e.idempotencyScope === "connection" ? b.Union([r, f]) : r), e.requiresApproval);
+}, q = {
+	query: [
+		i,
+		n,
+		t
+	],
+	stream: [
+		i,
+		n,
+		t
+	],
+	action: [
+		i,
+		n,
+		t,
+		m,
+		p,
+		h,
+		g
+	],
+	mutation: [
+		i,
+		n,
+		t,
+		d,
+		m,
+		p,
+		S,
+		h,
+		g
+	]
+}, J = (e, t) => R(W(B(e.errorSchema), e.guards), t), Y = (e, t) => ({
+	...e,
+	name: t
+}), X = (t, n) => x.make(t.name, {
+	payload: u(t.input, t.name, z(t.guards)),
+	success: e(t.output),
+	error: G(t, "query", n),
+	stream: !0
+}), Z = (e, t) => x.make(e.name, {
+	payload: u(e.input, e.name, z(e.guards)),
+	success: e.output,
+	error: G(e, "mutation", t)
+}), Q = (e, t) => x.make(e.name, {
+	payload: u(e.input, e.name, z(e.guards)),
+	success: e.output,
+	error: G(e, "action", t)
+}), $ = (e, t) => x.make(e.name, {
+	payload: u(e.input, e.name, z(e.guards)),
+	success: e.element,
+	error: G(e, "stream", t),
+	stream: !0
+}), re = (e) => {
+	switch (e.kind) {
+		case "query": return X(e);
+		case "mutation": return Z(e);
+		case "action": return Q(e);
+		case "stream": return $(e);
+	}
+}, ie = (e) => {
+	let t = e.input, n = t === void 0 ? {} : { input: t }, r = e.output, i = r === void 0 ? {} : { output: r }, a = {
+		...n,
+		...i,
+		error: e.error
+	};
+	if (e.kind === "query") return {
+		kind: "query",
+		source: e.source,
+		...a
+	};
+	if (e.kind === "action") return {
+		kind: "action",
+		...a
+	};
+	if (e.kind === "stream") return {
+		kind: "stream",
+		...a
+	};
+	let o = e.target, s = e.idempotencyScope === void 0 ? {} : { idempotencyScope: e.idempotencyScope }, c = e.serialize === void 0 ? {} : { serialize: e.serialize };
+	if (o === void 0) return {
+		kind: "mutation",
+		...a,
+		...s,
+		...c
+	};
+	let l = Array.isArray(o) ? o : [o];
+	return {
+		kind: "mutation",
+		...a,
+		...s,
+		...c,
+		targets: l.map((e) => ({
+			table: e.table,
+			op: e.op,
+			..."order" in e && e.order !== void 0 ? { order: e.order } : {},
+			..."shape" in e && e.shape !== void 0 ? { shape: e.shape } : {},
+			..."identify" in e && e.identify !== void 0 ? { identify: e.identify } : {},
+			..."path" in e && e.path !== void 0 ? { path: e.path } : {},
+			..."by" in e && e.by !== void 0 ? { by: e.by } : {},
+			..."match" in e && e.match !== void 0 ? { match: e.match } : {},
+			..."shapeItem" in e && e.shapeItem !== void 0 ? { shapeItem: e.shapeItem } : {},
+			..."relations" in e && e.relations !== void 0 ? { relations: e.relations } : {}
+		}))
+	};
+};
+//#endregion
+export { q as FRAMEWORK_WIRE_ERRORS, D as SERVICE_NAME_PATTERN, Q as actionToRpc, I as defineAction, F as defineMutation, P as defineQuery, L as defineStream, M as hasAccessDecision, z as hasEnforcedGuard, ne as isAuthenticatedGuard, T as isClientReachable, te as isPolicyGuard, E as isServiceReachable, j as isUpgradedGuard, C as isWireReachable, Z as mutationToRpc, ie as normalizeDescriptor, X as queryToRpc, ee as requireUpgraded, $ as streamToRpc, re as toRpc, w as wireAudienceOf, G as wireErrorUnion, Y as withRpcTag, J as workflowWireErrorUnion };

package/dist/publicApi.js

@@ -0,0 +1,325 @@
+import { checkGuardsEffect as e } from "./scopes.js";
+import { declaredErrorTags as t, errorMemberSchema as n } from "./errorSchema.js";
+import { schemaShape as r, shapeDigest as i } from "./schemaShape.js";
+import { validateHttpStreamMaxDuration as a } from "./httpStreamMaxDuration.js";
+import { encodeRestError as o, resolveRestFormat as s, restViewSchema as c, toSnakeCase as l } from "./restFormat.js";
+import { RestRouteError as u, defineRestRoute as ee, requireAuthenticated as d, requireScope as f, response as p, sse as te, sseFrame as m } from "./rest.js";
+import { Effect as h, Schema as g, SchemaGetter as _, SchemaIssue as ne } from "effect";
+import * as v from "effect/SchemaAST";
+//#region src/publicApi.ts
+var y = (e, t, n) => t.method ?? (t.resource !== void 0 && n !== void 0 ? C("", t, n).method : void 0) ?? (e === "query" ? "GET" : "POST"), b = (e, t, n) => w(t.path ?? (t.resource !== void 0 && n !== void 0 ? C(e, t, n).path : `/${t.version ?? "v1"}/${e.replace(/\./g, "/")}`)), x = (e) => {
+	let t = e.split("/").pop() ?? e;
+	return t.endsWith("ies") ? `${t.slice(0, -3)}y` : t.endsWith("ses") || t.endsWith("xes") ? t.slice(0, -2) : t.endsWith("s") ? t.slice(0, -1) : t;
+}, S = (e, t) => {
+	let n = t != null && (typeof t == "object" || typeof t == "function") && "ast" in t ? F(t) : void 0;
+	if (n === void 0) return;
+	let r = `${x(e)}Id`;
+	return n.has(r) ? r : n.has("id") ? "id" : void 0;
+}, C = (e, t, n) => {
+	let r = (t.resource ?? "").replace(/^\/+|\/+$/g, ""), i = `/${t.version ?? "v1"}/${r}`, a = S(r, n.input), o = a === void 0 ? i : `${i}/:${a}`, s = e.split(".").pop() ?? e, c = n.target?.op;
+	return n.kind === "query" || n.kind === "stream" ? {
+		method: "GET",
+		path: o
+	} : n.kind === "mutation" && c === "insert" ? {
+		method: "POST",
+		path: i
+	} : n.kind === "mutation" && c === "update" ? {
+		method: a === void 0 ? "POST" : "PATCH",
+		path: o
+	} : n.kind === "mutation" && c === "delete" ? {
+		method: a === void 0 ? "POST" : "DELETE",
+		path: o
+	} : {
+		method: "POST",
+		path: `${o}/${s}`
+	};
+}, w = (e) => e.replace(/\{([A-Za-z0-9_]+)\}/g, ":$1"), T = (e) => [...e.matchAll(/:([A-Za-z0-9_]+)/g)].map((e) => e[1]), E = (e) => {
+	if (v.isUnion(e)) {
+		let t = e.types.filter((e) => !v.isUndefined(e));
+		if (t.length === 1) return t[0];
+		if (t.length !== e.types.length) return new v.Union(t);
+	}
+	return e;
+}, D = /^-?(\d+\.?\d*|\.\d+)(e[+-]?\d+)?$/i, O = (e, t) => {
+	let n = E(t);
+	if (n.encoding !== void 0) return O(e, v.toEncoded(n));
+	if (v.isUnion(n)) {
+		for (let t of n.types) {
+			let n = O(e, t);
+			if (n !== e) return n;
+		}
+		return e;
+	}
+	if (v.isArrays(n)) {
+		let t = Array.isArray(e) ? e : e === void 0 ? void 0 : [e];
+		if (t === void 0) return e;
+		let r = n.rest[0] ?? n.elements[0];
+		return r === void 0 ? t : t.map((e) => O(e, r));
+	}
+	if (typeof e != "string") return e;
+	if (v.isNumber(n)) return D.test(e.trim()) ? Number(e) : e;
+	if (v.isBoolean(n)) return e === "true" || e !== "false" && e;
+	if (v.isLiteral(n)) {
+		let t = n.literal;
+		return typeof t == "number" && D.test(e.trim()) && Number(e) === t || typeof t == "boolean" && String(t) === e ? t : e;
+	}
+	return e;
+}, k = (e, t) => {
+	if (typeof e != "object" || !e || Array.isArray(e)) return e;
+	let n = E(v.toEncoded(t.ast));
+	if (!v.isObjects(n)) return e;
+	let r = { ...e };
+	for (let e of n.propertySignatures) {
+		let t = String(e.name);
+		t in r && (r[t] = O(r[t], e.type));
+	}
+	return r;
+}, re = (e) => {
+	let t = E(v.toEncoded(e.ast));
+	if (!v.isObjects(t)) return (e) => e;
+	let n = t.propertySignatures, r = /* @__PURE__ */ new Map(), i = n.length >= 32 && n.every((e, t) => typeof e.name != "string" || e.name in Object.prototype || r.has(e.name) ? !1 : (r.set(e.name, {
+		type: e.type,
+		order: t
+	}), !0));
+	return (e) => {
+		if (typeof e != "object" || !e || Array.isArray(e)) return e;
+		let t = { ...e }, a = i ? Object.keys(t) : void 0;
+		if (a !== void 0 && a.length * 4 < n.length) {
+			let e = [];
+			for (let t of a) {
+				let n = r.get(t);
+				n !== void 0 && e.push({
+					key: t,
+					...n
+				});
+			}
+			e.sort((e, t) => e.order - t.order);
+			for (let { key: n, type: r } of e) t[n] = O(t[n], r);
+		} else for (let e of n) {
+			let n = String(e.name);
+			n in t && (t[n] = O(t[n], e.type));
+		}
+		return t;
+	};
+}, A = (e, t, n) => {
+	if (n !== void 0) try {
+		let r = g.encodeUnknownSync(n)(e);
+		if (typeof r == "object" && r && !Array.isArray(r)) return {
+			error: t,
+			...r
+		};
+	} catch {}
+	throw Error("Typed REST failure is incompatible with its declared schema");
+}, j = (e, n, r, i = []) => M(e, n, r, i, t), M = (e, t, n, r, i) => {
+	if (typeof e != "object" || !e) return e;
+	let a = e._tag;
+	if (typeof a != "string" || a === "ScopeError" || a === "NoSuchResource") return e;
+	if (i(t.error).has(a)) {
+		let r = n.errorStatus?.[a] ?? 422;
+		return new u(r, A(e, a, t.error));
+	}
+	let o = r.find((e) => i(e.schema).has(a));
+	if (o === void 0) return e;
+	let s = n.errorStatus?.[a] ?? o.rest?.status ?? 422, c = o.rest?.headers?.(e);
+	return new u(s, A(e, a, o.schema), c);
+}, N = (e, t, n, r, i, a, s) => {
+	let c = M(e, t, n, r, s);
+	if (!(c instanceof u) || i.errors === "tagged" && i.encodeError === void 0) return c;
+	let { error: l, _tag: ee, ...d } = c.body, f = typeof d.message == "string" ? d.message : typeof d.reason == "string" ? d.reason : "", p = o(i, {
+		status: c.status,
+		tag: l,
+		message: f,
+		fields: d
+	}, {
+		...a,
+		status: c.status
+	});
+	return new u(c.status, p.body, {
+		...c.headers ?? {},
+		...p.headers ?? {}
+	}, p.contentType);
+}, P = (e) => e.split(".").map((e, t) => t === 0 ? e : e.charAt(0).toUpperCase() + e.slice(1)).join("").replace(/[^A-Za-z0-9_]/g, "_"), F = (e) => {
+	let t = E(v.toEncoded(e.ast));
+	return v.isObjects(t) && t.indexSignatures.length === 0 ? new Set(t.propertySignatures.map((e) => String(e.name))) : void 0;
+}, I = (e, t) => e === t || JSON.stringify(e) === JSON.stringify(t), ie = (e) => {
+	let t = E(v.toEncoded(e.ast)), n = v.isObjects(t) ? new Map(t.propertySignatures.map((e) => [String(e.name), e.type])) : /* @__PURE__ */ new Map();
+	return (e) => {
+		let t = {};
+		for (let [r, i] of Object.entries(e)) {
+			let e = n.get(r);
+			t[r] = e === void 0 ? i : O(i, e);
+		}
+		return t;
+	};
+}, L = (e, t) => {
+	if (e !== void 0) {
+		try {
+			return g.encodeUnknownSync(t)(e);
+		} catch {}
+		try {
+			return g.decodeUnknownSync(t)(e), e;
+		} catch {}
+		return e;
+	}
+}, R = (e, t, n) => ({
+	...e.request === void 0 ? {} : { request: L(e.request, t) },
+	...e.response === void 0 ? {} : { response: L(e.response, n) }
+}), ae = () => (e) => {
+	if (e.subject.type !== "anonymous") return;
+	let t = e.subject.credentialRejected;
+	return t === void 0 ? void 0 : {
+		status: 401,
+		message: t
+	};
+}, z = (n, r, i, o = {}) => {
+	let u = n.publicApi;
+	if (u === void 0) throw Error(`publicApiRoute: descriptor '${n.name}' has no publicApi annotation`);
+	let x = s(o.profile, u.format), S = o.pluginErrors ?? [], C = /* @__PURE__ */ new WeakMap(), w = (e) => {
+		if (e === void 0) return /* @__PURE__ */ new Set();
+		let n = C.get(e.ast);
+		if (n !== void 0) return n;
+		let r = t(e);
+		return C.set(e.ast, r), r;
+	}, E = /* @__PURE__ */ new WeakMap(), D = (e, t) => {
+		if (e === void 0) return;
+		let n = E.get(e.ast);
+		if (n === void 0) {
+			let t = /* @__PURE__ */ new Map();
+			for (let n of v.isUnion(e.ast) ? e.ast.types : [e.ast]) {
+				let e = g.make(n);
+				for (let n of w(e)) t.has(n) || t.set(n, e);
+			}
+			n = t, E.set(e.ast, n);
+		}
+		return n.get(t);
+	}, O = {
+		kind: n.kind,
+		input: n.input,
+		target: n.target
+	}, k = y(n.kind, u, O), A = (e) => x.naming === "snake_case" ? l(e) : e, j = b(n.name, u, O), M = j.replace(/:([A-Za-z0-9_]+)/g, (e, t) => `:${A(t)}`), L = T(M), z = c(n.input, x), B = re(z), V = ie(z), H = F(z);
+	if (H !== void 0) {
+		for (let e of L) if (!H.has(e)) throw Error(`publicApi: descriptor '${n.name}' — path '${j}' binds ':${e}', and the input declares no field of that name` + (H.size > 0 ? ` (fields: ${[...H].join(", ")})` : " (the input declares no fields)"));
+	}
+	let U = c(n.output, x), oe = g.Struct({ value: z }), W = k !== "GET" && H === void 0;
+	if (k !== "GET" && H !== void 0) {
+		let e = L.length >= 32 ? new Set(L) : void 0;
+		for (let t of H) if (!(e?.has(t) ?? L.includes(t))) {
+			W = !0;
+			break;
+		}
+	}
+	let G = {
+		query: g.Unknown,
+		params: g.Unknown,
+		form: g.Boolean
+	}, se = (W ? g.Struct({
+		...G,
+		body: g.Unknown
+	}) : g.Struct(G)).pipe(g.decodeTo(oe, {
+		decode: _.transformEffect((e) => {
+			let t = "body" in e ? e.body : void 0, n = k === "GET" ? B(e.query) : e.form ? B(t ?? {}) : t ?? {}, r = typeof e.params == "object" && e.params !== null ? V(e.params) : {};
+			if (typeof n != "object" || !n || Array.isArray(n)) return h.succeed({ value: n });
+			let i = n, a = Object.keys(r), o = 0;
+			for (let e of a) e in i && !I(i[e], r[e]) && (a[o++] = e);
+			if (a.length = o, a.length > 0) {
+				let t = k === "GET" ? "query string" : "body";
+				return h.fail(new ne.InvalidValue({ message: `${a.map((e) => `'${e}'`).join(", ")} ${a.length === 1 ? "is" : "are"} bound by the path and sent with another value in the ${t}` }, e));
+			}
+			return h.succeed({ value: {
+				...i,
+				...r
+			} });
+		}),
+		encode: _.transform((e) => e)
+	})), K = [
+		ae(),
+		...n.openAccess === void 0 ? [d()] : [],
+		...(u.scopes ?? []).map((e) => f(e))
+	], q = (() => {
+		let e = n.source;
+		return typeof e == "string" ? e : Array.isArray(e) ? e[0] : void 0;
+	})(), ce = (e, t = 200) => ({
+		tag: n.name,
+		method: e.method,
+		path: e.path,
+		query: e.query,
+		source: q,
+		status: t
+	});
+	K.push(async (t, r) => {
+		if (r === void 0 || typeof r.input != "object" || r.input === null) throw Error("Projected REST admission input is unavailable");
+		let i = await h.runPromise(e(t.subject, n.guards, r.input.value, {
+			defaultDeny: r.defaultDeny,
+			procedure: n.name
+		}));
+		if (i) throw i;
+	});
+	let J = u.stream === "sse" && n.kind === "query" && i !== void 0, Y = a(u.streamMaxDurationMs);
+	if (Y !== void 0 && !J) throw Error(`${n.name}: streamMaxDurationMs requires an SSE query subscription`);
+	let le = J ? (e, t) => te((n) => i(e.value, t, (e) => {
+		n(m(String(e._tag ?? "message"), e));
+	}), Y === void 0 ? {} : { maxDurationMs: Y }) : async (e, t) => {
+		let n = await r(e.value, t);
+		return p(n);
+	}, X = n.error, Z = w(X), ue = [...Z], Q = [];
+	for (let e of Object.values(u.additionalErrorStatuses ?? {})) if (e.some((e) => !Number.isInteger(e) || e < 400 || e > 599)) throw Error(`publicApi.additionalErrorStatuses for ${n.name} must contain HTTP error statuses (400–599)`);
+	let $ = (e, t, n) => {
+		for (let r of /* @__PURE__ */ new Set([t, ...u.additionalErrorStatuses?.[e] ?? []])) Q.some((t) => t.tag === e && t.status === r) || Q.push({
+			status: r,
+			tag: e,
+			schema: n
+		});
+	};
+	for (let e of ue) {
+		let t = D(X, e);
+		t !== void 0 && $(e, u.errorStatus?.[e] ?? 422, t);
+	}
+	for (let e of S) for (let t of w(e.schema)) Z.has(t) || $(t, u.errorStatus?.[t] ?? e.rest?.status ?? 422, D(e.schema, t) ?? e.schema);
+	let de = u.security === !1 ? "none" : u.security ?? (n.openAccess === void 0 ? "required" : "optional"), fe = {
+		tag: n.name,
+		kind: n.kind,
+		version: u.version ?? "v1",
+		security: de,
+		idempotent: u.idempotent === !0,
+		input: z,
+		pathParams: L,
+		output: U,
+		source: q,
+		errorResponses: Q,
+		format: x
+	};
+	return ee({
+		publicApiDescriptor: n,
+		mapFailure: (e, t) => N(e, n, u, S, x, ce(t), w),
+		method: k,
+		path: M,
+		input: se,
+		output: U,
+		handler: le,
+		...J ? { streaming: !0 } : {},
+		guards: K,
+		operationId: u.operationId ?? P(n.name),
+		tags: u.tags ?? [n.name.split(".")[0] ?? n.name],
+		projection: fe,
+		...x.etag && k === "GET" && !J ? { etag: !0 } : {},
+		...u.cache !== void 0 && k === "GET" && !J ? { cache: u.cache } : {},
+		...u.example === void 0 ? {} : { example: R(u.example, z, U) },
+		...u.summary === void 0 ? {} : { summary: u.summary },
+		...u.description === void 0 ? {} : { description: u.description },
+		...u.deprecated === void 0 ? {} : { deprecated: u.deprecated },
+		...u.sunset === void 0 ? {} : { sunset: u.sunset }
+	});
+}, B = (e, t = {}) => e.filter((e) => e.descriptor.publicApi !== void 0).map((e) => z(e.descriptor, e.invoke, e.subscribe, t)).sort((e, t) => e.path.localeCompare(t.path)), V = (e) => i(e.filter((e) => e.projection !== void 0).map((e) => {
+	let t = e.projection, n = {
+		tag: t.tag,
+		method: e.method,
+		path: e.path,
+		pathParams: t.pathParams,
+		version: t.version,
+		security: t.security,
+		errors: [...t.errorResponses].map((e) => `${e.status}:${e.tag}`).sort()
+	};
+	return `${JSON.stringify(n)} ${r(t.input.ast)} ${r(t.output.ast)}`;
+}).sort().join("\n"));
+//#endregion
+export { k as coerceQueryObject, O as coerceQueryValue, B as collectPublicApiRoutes, t as declaredErrorTags, y as derivePublicMethod, b as derivePublicPath, C as deriveResource, n as errorMemberSchema, w as normalizePathParams, P as operationIdOf, T as pathParamNames, j as projectedFailure, z as publicApiRoute, V as publicSurfaceDigest, S as resourceIdField, R as wireExample };

package/dist/queryOptionalSources.js

@@ -0,0 +1,14 @@
+//#region src/queryOptionalSources.ts
+var e = (e, t, n) => {
+	if (n === void 0) return;
+	let r = new Set(t === void 0 ? [] : typeof t == "string" ? [t] : t), i = () => /* @__PURE__ */ Error(`${e}: optionalSource must contain unique names already declared in source`);
+	if (!Array.isArray(n)) throw i();
+	let a = [];
+	for (let e of n) {
+		if (typeof e != "string" || e.length === 0 || !r.has(e) || a.includes(e)) throw i();
+		a.push(e);
+	}
+	return Object.freeze(a);
+};
+//#endregion
+export { e as captureOptionalQuerySources };

package/dist/reactivityChannel.js

@@ -0,0 +1,34 @@
+//#region src/reactivityChannel.ts
+var e = "channel:", t = Symbol.for("@voltro/protocol/reactivityChannels"), n = globalThis, r = n[t] ?? (n[t] = /* @__PURE__ */ new Map()), i = /^[a-z][a-z0-9-]*(\.[a-z0-9-]+)*$/, a = (t) => {
+	if (!i.test(t)) throw Error(`reactivityChannel('${t}'): invalid channel name.\n  Use lowercase kebab segments separated by dots — \`presence\`, \`job-queue\`,
+  \`billing.usage\`. A \`:\` is refused because it is the namespace separator in
+  the routing key (\`${e}<name>\`), and an uppercase letter is\n  refused because a key that differs only by case reads as one channel and
+  routes as two.`);
+	let n = r.get(t);
+	if (n !== void 0) return n;
+	let a = `${e}${t}`, o = Object.freeze({
+		kind: "reactivity-channel",
+		name: t,
+		key: a,
+		toString: () => a
+	});
+	return r.set(t, o), o;
+}, o = (e) => typeof e == "object" && !!e && e.kind === "reactivity-channel", s = (t) => t.startsWith(e), c = () => new Set([...r.values()].map((e) => e.key)), l = (e) => o(e) ? e.key : e, u = (e) => e === void 0 ? [] : Array.isArray(e) ? e.map(l) : [l(e)], d = (e) => e === void 0 ? void 0 : Array.isArray(e) ? e.map(l) : l(e), f = (e) => {
+	let t = c(), n = [];
+	for (let r of e) for (let e of u(r.source)) s(e) && !t.has(e) && n.push({
+		procedure: r.name,
+		key: e
+	});
+	return n;
+}, p = (e, t) => {
+	let n = e?.injectExternalChange;
+	return n !== void 0 && (n.call(e, {
+		table: t.key,
+		op: "update",
+		new: {},
+		old: {},
+		origin: "inline"
+	}), !0);
+};
+//#endregion
+export { e as REACTIVITY_CHANNEL_PREFIX, c as declaredReactivityChannelKeys, o as isReactivityChannel, s as isReactivityChannelKey, d as normalizeSource, p as publishReactivity, a as reactivityChannel, u as sourceKeys, f as undeclaredChannelKeys };