@voltro/protocol 0.81.0 → 0.83.0

package/dist/inspect.d.ts

@@ -2,9 +2,9 @@ import { ParseOptions } from 'effect/SchemaAST';
 import { Schema } from 'effect';
 
 export declare const decodeInspectBackfillInput: (u: unknown, overrideOptions?: ParseOptions) => {
-    readonly from: string;
     readonly name: string;
     readonly limit: number;
+    readonly from: string;
     readonly to: string;
     readonly requestId: string;
     readonly confirm: boolean;
@@ -71,6 +71,18 @@ export declare const InspectBackfillResultSchema: Schema.Union<[Schema.Struct<{
     reason: typeof Schema.String;
 }>]>;
 
+export declare type InspectCommandRejection = typeof InspectCommandRejectionSchema.Type;
+
+export declare const inspectCommandRejection: (status: number, message: string) => InspectCommandRejection | undefined;
+
+/** Explicit non-acceptance from an Inspect command endpoint. Transport errors,
+ * conflicts with an earlier request and server failures are not this outcome. */
+export declare const InspectCommandRejectionSchema: Schema.Struct<{
+    kind: Schema.Literal<["rejected"]>;
+    status: Schema.Literal<[400, 401, 403, 404]>;
+    message: typeof Schema.String;
+}>;
+
 export declare type InspectReplicaSelection = {
     readonly mode: 'all';
 } | {
@@ -78,10 +90,82 @@ export declare type InspectReplicaSelection = {
     readonly replicaIds: ReadonlyArray<string>;
 };
 
+export declare type InspectWorkflowExecutionObservation = typeof InspectWorkflowExecutionObservationSchema.Type;
+
+/** A projection of engine evidence, not a run-row or recorder-entry claim.
+ * Deliberately excludes payloads, outputs, raw causes and journal identifiers. */
+export declare const InspectWorkflowExecutionObservationSchema: Schema.Union<[Schema.Struct<{
+    kind: Schema.Literal<["not-observed"]>;
+    workflowName: Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>;
+    executionId: Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>;
+}>, Schema.Struct<{
+    kind: Schema.Literal<["pending"]>;
+    workflowName: Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>;
+    executionId: Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>;
+}>, Schema.Struct<{
+    kind: Schema.Literal<["delivery-failed"]>;
+    workflowName: Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>;
+    executionId: Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>;
+}>, Schema.Struct<{
+    kind: Schema.Literal<["suspended"]>;
+    workflowName: Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>;
+    executionId: Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>;
+}>, Schema.Struct<{
+    kind: Schema.Literal<["completed"]>;
+    outcome: Schema.Literal<["succeeded", "failed", "cancelled"]>;
+    workflowName: Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>;
+    executionId: Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>;
+}>]>;
+
+export declare type InspectWorkflowExecutionTarget = typeof InspectWorkflowExecutionTargetSchema.Type;
+
+/** Read an existing execution identity; this is never a start command. */
+export declare const InspectWorkflowExecutionTargetSchema: Schema.Struct<{
+    workflowName: Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>;
+    executionId: Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>;
+}>;
+
+export declare type InspectWorkflowQueuedStartObservation = typeof InspectWorkflowQueuedStartObservationSchema.Type;
+
+/** Read-only admission evidence. Accepted means an execution exists, not that it succeeded. */
+export declare const InspectWorkflowQueuedStartObservationSchema: Schema.Union<[Schema.Struct<{
+    kind: Schema.Literal<["pending"]>;
+    workflowName: Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>;
+    receiptId: Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>;
+    tenantId: Schema.NullOr<Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>>;
+}>, Schema.Struct<{
+    kind: Schema.Literal<["accepted"]>;
+    executionId: Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>;
+    workflowName: Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>;
+    receiptId: Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>;
+    tenantId: Schema.NullOr<Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>>;
+}>, Schema.Struct<{
+    kind: Schema.Literal<["not-executed"]>;
+    reason: Schema.Literal<["dropped", "skipped", "superseded", "cancelled", "abandoned", "rejected"]>;
+    workflowName: Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>;
+    receiptId: Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>;
+    tenantId: Schema.NullOr<Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>>;
+}>]>;
+
+export declare type InspectWorkflowQueuedStartTarget = typeof InspectWorkflowQueuedStartTargetSchema.Type;
+
+/** A caller receipt, never an execution or a reusable admission slot. */
+export declare const InspectWorkflowQueuedStartTargetSchema: Schema.Struct<{
+    workflowName: Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>;
+    receiptId: Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>;
+    tenantId: Schema.NullOr<Schema.filter<Schema.filter<typeof Schema.NonEmptyString>>>;
+}>;
+
 export declare class InvalidReplicaSelection extends Error {
     readonly name = "InvalidReplicaSelection";
 }
 
+export declare const isInspectCommandRejection: (u: unknown, overrideOptions?: ParseOptions | number) => u is {
+    readonly status: 400 | 401 | 403 | 404;
+    readonly kind: "rejected";
+    readonly message: string;
+};
+
 /** Repeated parameters preserve IDs containing commas, spaces or punctuation. */
 export declare const parseReplicaSelection: (params: URLSearchParams) => InspectReplicaSelection | undefined;
 

package/dist/inspect.js

@@ -1,85 +1,130 @@
 import { Schema as e } from "effect";
-//#region src/inspectBackfill.ts
-var t = e.String.pipe(e.filter((e) => Number.isFinite(Date.parse(e)))), n = e.String.pipe(e.minLength(1), e.maxLength(256)), r = e.Struct({
-	id: n,
-	name: n,
-	from: t,
-	to: t,
+//#region src/inspectWorkflowQueuedStart.ts
+var t = e.NonEmptyString.pipe(e.maxLength(1024), e.filter((e) => e.trim().length > 0 && !/[\u0000-\u001f\u007f]/.test(e))), n = e.Struct({
+	workflowName: t,
+	receiptId: t,
+	tenantId: e.NullOr(t)
+}), r = n.fields, i = e.Union(e.Struct({
+	...r,
+	kind: e.Literal("pending")
+}), e.Struct({
+	...r,
+	kind: e.Literal("accepted"),
+	executionId: t
+}), e.Struct({
+	...r,
+	kind: e.Literal("not-executed"),
+	reason: e.Literal("dropped", "skipped", "superseded", "cancelled", "abandoned", "rejected")
+})), a = e.Struct({
+	kind: e.Literal("rejected"),
+	status: e.Literal(400, 401, 403, 404),
+	message: e.String
+}), o = e.is(a), s = (e, t) => {
+	let n = {
+		kind: "rejected",
+		status: e,
+		message: t
+	};
+	return o(n) ? n : void 0;
+}, c = e.String.pipe(e.filter((e) => Number.isFinite(Date.parse(e)))), l = e.String.pipe(e.minLength(1), e.maxLength(256)), u = e.Struct({
+	id: l,
+	name: l,
+	from: c,
+	to: c,
 	occurrences: e.Array(e.Number),
 	status: e.Literal("queued", "running", "completed", "interrupted"),
 	owner: e.NullOr(e.String),
-	createdAt: t,
-	updatedAt: t,
+	createdAt: c,
+	updatedAt: c,
 	cursor: e.Number,
 	activeIndex: e.NullOr(e.Number),
 	results: e.Array(e.Struct({
-		runId: n,
+		runId: l,
 		status: e.Literal("succeeded", "failed", "skipped", "missed")
 	})),
 	error: e.NullOr(e.String)
-}), i = e.Struct({
-	requestId: n,
-	name: n,
-	from: t,
-	to: t,
+}), d = e.Struct({
+	requestId: l,
+	name: l,
+	from: c,
+	to: c,
 	confirm: e.Boolean,
 	limit: e.Number.pipe(e.int(), e.between(1, 1e4))
-}), a = e.decodeUnknownSync(i), o = e.Union(e.Struct({
+}), f = e.decodeUnknownSync(d), p = e.Union(e.Struct({
 	kind: e.Literal("accepted"),
-	request: r
+	request: u
 }), e.Struct({
 	kind: e.Literal("refused"),
-	name: n,
+	name: l,
 	occurrences: e.Number,
 	reason: e.String
-})), s = class extends Error {
+})), m = class extends Error {
 	name = "ScheduleBackfillRequestConflict";
-}, c = (e) => typeof e == "object" && e && !Array.isArray(e) ? e : void 0, l = (e) => Array.isArray(e) && e.every((e) => c(e) !== void 0) ? e : void 0, u = (e) => typeof e == "number" && Number.isFinite(e) ? e : 0, d = /* @__PURE__ */ new Set([
+}, h = e.NonEmptyString.pipe(e.maxLength(1024), e.filter((e) => e.trim().length > 0 && !/[\u0000-\u001f\u007f]/.test(e))), g = e.Struct({
+	workflowName: h,
+	executionId: h
+}), _ = g.fields, v = e.Union(e.Struct({
+	..._,
+	kind: e.Literal("not-observed")
+}), e.Struct({
+	..._,
+	kind: e.Literal("pending")
+}), e.Struct({
+	..._,
+	kind: e.Literal("delivery-failed")
+}), e.Struct({
+	..._,
+	kind: e.Literal("suspended")
+}), e.Struct({
+	..._,
+	kind: e.Literal("completed"),
+	outcome: e.Literal("succeeded", "failed", "cancelled")
+})), y = (e) => typeof e == "object" && e && !Array.isArray(e) ? e : void 0, b = (e) => Array.isArray(e) && e.every((e) => y(e) !== void 0) ? e : void 0, x = (e) => typeof e == "number" && Number.isFinite(e) ? e : 0, S = /* @__PURE__ */ new Set([
 	"counter",
 	"gauge",
 	"histogram",
 	"summary",
 	"frequency"
-]), f = (e) => {
-	let t = l(e);
-	return t?.every((e) => typeof e.name == "string" && d.has(String(e.type))) ? t : void 0;
-}, p = (e) => {
-	let t = c(e), n = c(t?.data), r = l(n?.results);
+]), C = (e) => {
+	let t = b(e);
+	return t?.every((e) => typeof e.name == "string" && S.has(String(e.type))) ? t : void 0;
+}, w = (e) => {
+	let t = y(e), n = y(t?.data), r = b(n?.results);
 	if (!t || !n?.selection || !r) return e;
 	let i = r.filter((e) => e.status === "answered").map((e) => ({
 		replicaId: String(e.replicaId),
-		observation: c(e.observation),
-		data: c(e.observation)?.data
+		observation: y(e.observation),
+		data: y(e.observation)?.data
 	}));
 	if (i.length === 0) throw Error("None of the selected replicas answered. Check replica availability and retry.");
 	let a = i.map((e) => ({
 		...e,
-		object: c(e.data)
-	})), o = (e) => a.reduce((t, n) => t + u(n.object?.[e]), 0), s = Math.max(...i.map((e) => u(e.observation?.capturedAt))), d = {
+		object: y(e.data)
+	})), o = (e) => a.reduce((t, n) => t + x(n.object?.[e]), 0), s = Math.max(...i.map((e) => x(e.observation?.capturedAt))), c = {
 		capturedAt: s,
 		bufferSize: o("bufferSize"),
 		bufferCapacity: o("bufferCapacity")
-	}, p;
-	if (a.every((e) => l(e.object?.records))) {
-		let e = a.flatMap((e) => l(e.object?.records).map((t) => ({
+	}, l;
+	if (a.every((e) => b(e.object?.records))) {
+		let e = a.flatMap((e) => b(e.object?.records).map((t) => ({
 			...t,
 			fields: {
-				...c(t.fields),
+				...y(t.fields),
 				"voltro.replica": e.replicaId
 			}
-		}))).sort((e, t) => u(e.ts) - u(t.ts));
-		p = {
-			...d,
+		}))).sort((e, t) => x(e.ts) - x(t.ts));
+		l = {
+			...c,
 			returned: e.length,
 			records: e
 		};
-	} else if (a.every((e) => l(e.object?.traces))) {
+	} else if (a.every((e) => b(e.object?.traces))) {
 		let e = /* @__PURE__ */ new Map();
-		for (let t of a) for (let n of l(t.object?.traces)) {
-			let r = String(n.traceId), i = (l(n.spans) ?? []).map((e) => ({
+		for (let t of a) for (let n of b(t.object?.traces)) {
+			let r = String(n.traceId), i = (b(n.spans) ?? []).map((e) => ({
 				...e,
 				attributes: {
-					...c(e.attributes),
+					...y(e.attributes),
 					"voltro.replica": t.replicaId
 				}
 			})), a = e.get(r) ?? [];
@@ -89,7 +134,7 @@ var t = e.String.pipe(e.filter((e) => Number.isFinite(Date.parse(e)))), n = e.St
 			}), e.set(r, a);
 		}
 		let t = [...e.values()].map((e) => {
-			let t = e.flatMap((e) => l(e.spans) ?? []).sort((e, t) => u(e.startMs) - u(t.startMs)), n = [...e].sort((e, t) => u(e.startMs) - u(t.startMs))[0], r = Math.min(...e.map((e) => u(e.startMs))), i = Math.max(...e.map((e) => u(e.startMs) + u(e.durationMs)));
+			let t = e.flatMap((e) => b(e.spans) ?? []).sort((e, t) => x(e.startMs) - x(t.startMs)), n = [...e].sort((e, t) => x(e.startMs) - x(t.startMs))[0], r = Math.min(...e.map((e) => x(e.startMs))), i = Math.max(...e.map((e) => x(e.startMs) + x(e.durationMs)));
 			return {
 				...n,
 				startMs: r,
@@ -97,65 +142,65 @@ var t = e.String.pipe(e.filter((e) => Number.isFinite(Date.parse(e)))), n = e.St
 				spanCount: t.length,
 				hasError: e.some((e) => e.hasError === !0),
 				spans: t,
-				...e.some((e) => e.deliveryCount !== void 0) ? { deliveryCount: e.reduce((e, t) => e + u(t.deliveryCount), 0) } : {},
-				...e.some((e) => e.lastDeliveryMs !== void 0) ? { lastDeliveryMs: Math.max(...e.map((e) => u(e.lastDeliveryMs))) } : {}
+				...e.some((e) => e.deliveryCount !== void 0) ? { deliveryCount: e.reduce((e, t) => e + x(t.deliveryCount), 0) } : {},
+				...e.some((e) => e.lastDeliveryMs !== void 0) ? { lastDeliveryMs: Math.max(...e.map((e) => x(e.lastDeliveryMs))) } : {}
 			};
 		}).sort((e, t) => t.startMs - e.startMs);
-		p = {
-			...d,
+		l = {
+			...c,
 			returned: t.length,
 			traces: t
 		};
-	} else if (a.every((e) => l(e.object?.buckets) && typeof e.object?.windowMs == "number")) p = {
+	} else if (a.every((e) => b(e.object?.buckets) && typeof e.object?.windowMs == "number")) l = {
 		capturedAt: s,
-		windowMs: Math.max(...a.map((e) => u(e.object?.windowMs))),
+		windowMs: Math.max(...a.map((e) => x(e.object?.windowMs))),
 		totalSamples: o("totalSamples"),
-		buckets: a.flatMap((e) => l(e.object?.buckets).map((t) => ({
+		buckets: a.flatMap((e) => b(e.object?.buckets).map((t) => ({
 			...t,
 			tag: `${String(t.tag)} [${e.replicaId}]`
 		})))
 	};
-	else if (i.every((e) => f(e.data))) p = i.flatMap((e) => f(e.data).map((t) => ({
+	else if (i.every((e) => C(e.data))) l = i.flatMap((e) => C(e.data).map((t) => ({
 		...t,
 		labels: {
-			...c(t.labels),
+			...y(t.labels),
 			voltro_replica: e.replicaId
 		}
 	})));
-	else if (a.every((e) => f(e.object?.samples))) p = { samples: a.flatMap((e) => f(e.object?.samples).map((t) => ({
+	else if (a.every((e) => C(e.object?.samples))) l = { samples: a.flatMap((e) => C(e.object?.samples).map((t) => ({
 		...t,
 		labels: {
-			...c(t.labels),
+			...y(t.labels),
 			voltro_replica: e.replicaId
 		}
 	}))) };
-	else if (r.length === 1 && i.length === 1) p = i[0].data;
+	else if (r.length === 1 && i.length === 1) l = i[0].data;
 	else throw Error("This view must compare observations per replica; its values cannot be safely combined.");
 	return {
 		...t,
-		data: p
+		data: l
 	};
-}, m = class extends Error {
+}, T = class extends Error {
 	name = "InvalidReplicaSelection";
-}, h = (e) => {
+}, E = (e) => {
 	let t = e.getAll("replicas"), n = e.getAll("replica");
 	if (t.length !== 0 || n.length !== 0) {
-		if (t.length > 1 || t.length === 1 && t[0] !== "all" || t.length > 0 && n.length > 0) throw new m("Choose all replicas or explicit replica IDs, not both.");
+		if (t.length > 1 || t.length === 1 && t[0] !== "all" || t.length > 0 && n.length > 0) throw new T("Choose all replicas or explicit replica IDs, not both.");
 		if (t[0] === "all") return { mode: "all" };
-		if (n.some((e) => e.trim().length === 0 || e.length > 512 || /[\u0000-\u001f\u007f]/.test(e))) throw new m("Replica IDs must be nonempty and contain no control characters.");
+		if (n.some((e) => e.trim().length === 0 || e.length > 512 || /[\u0000-\u001f\u007f]/.test(e))) throw new T("Replica IDs must be nonempty and contain no control characters.");
 		return {
 			mode: "selected",
 			replicaIds: [...new Set(n)].sort()
 		};
 	}
-}, g = (e, t) => {
+}, D = (e, t) => {
 	let n = e.indexOf("#"), r = n < 0 ? "" : e.slice(n), i = n < 0 ? e : e.slice(0, n), a = i.indexOf("?"), o = a < 0 ? i : i.slice(0, a), s = new URLSearchParams(a < 0 ? "" : i.slice(a + 1));
 	if (s.delete("replica"), s.delete("replicas"), t.mode === "all") s.set("replicas", "all");
 	else {
-		if (t.replicaIds.length === 0) throw new m("Select at least one replica.");
+		if (t.replicaIds.length === 0) throw new T("Select at least one replica.");
 		for (let e of [...new Set(t.replicaIds)].sort()) s.append("replica", e);
 	}
-	return h(s), `${o}?${s}${r}`;
+	return E(s), `${o}?${s}${r}`;
 };
 //#endregion
-export { i as InspectBackfillInputSchema, r as InspectBackfillReceiptSchema, o as InspectBackfillResultSchema, m as InvalidReplicaSelection, s as ScheduleBackfillRequestConflict, a as decodeInspectBackfillInput, h as parseReplicaSelection, p as projectReplicaObservation, g as withReplicaSelection };
+export { d as InspectBackfillInputSchema, u as InspectBackfillReceiptSchema, p as InspectBackfillResultSchema, a as InspectCommandRejectionSchema, v as InspectWorkflowExecutionObservationSchema, g as InspectWorkflowExecutionTargetSchema, i as InspectWorkflowQueuedStartObservationSchema, n as InspectWorkflowQueuedStartTargetSchema, T as InvalidReplicaSelection, m as ScheduleBackfillRequestConflict, f as decodeInspectBackfillInput, s as inspectCommandRejection, o as isInspectCommandRejection, E as parseReplicaSelection, w as projectReplicaObservation, D as withReplicaSelection };

package/dist/jwt.d.ts

@@ -26,7 +26,7 @@ declare interface AuthStrategy {
     readonly resolve: (input: AuthStrategyInput) => Promise<StrategyResolution> | StrategyResolution;
     /**
      * The bearer-token PREFIX this strategy claims, when it gates on one
-     * (`'sk_'`, `'awb_'`). Declared so a collision is DETECTABLE.
+     * (`'sk_'`, `'acme_'`). Declared so a collision is DETECTABLE.
      *
      * Two strategies claiming the same prefix is not a harmless duplicate: the
      * chain is first-match-wins, so whichever runs first decides the Subject —

package/dist/rest.d.ts

@@ -440,7 +440,7 @@ declare interface NestedTargetFields<Input = unknown> {
     /** Guard WHICH cached query entries this target patches: only entries whose
      *  CURRENT value satisfies the predicate. Pure + browser-safe. Prevents a
      *  patch from bleeding across sibling subscriptions that share a source table
-     *  (the guard AWB hand-writes as `roadmap.id === input.roadmapId`). Absent →
+     *  (the guard an app would otherwise hand-write as `roadmap.id === input.roadmapId`). Absent →
      *  every entry matching the target `table` is patched. */
     readonly match?: ((value: unknown, input: Input) => boolean) | undefined;
 }
@@ -799,7 +799,8 @@ export declare const problemTypeOf: (tag: string) => string;
  * and the status `errorStatus` assigns (`422` by default, the status the
  * OpenAPI projection already documents for a typed error); a plugin's
  * cross-cutting error answers under the status the plugin names. Anything
- * else is rethrown for the desugar's shared mapping (`ScopeError` → 403/401, a
+ * else is rethrown for the desugar's shared mapping (`ScopeError` → 403/401,
+ * a resource guard's `NoSuchResource` → 404, a
  * `status`-carrying error → itself, the rest → 500). The body is the tagged
  * `{ error, …fields }` form; `projectedFailureFor` speaks the profile.
  */
@@ -986,6 +987,13 @@ declare interface PublicApiSpec {
      * optional, the rest inherited. See `PublicApiProfileConfig`.
      */
     readonly format?: PublicApiProfileConfig;
+    /**
+     * GET only: how long a CDN may keep a successful answer, and the tags it can
+     * purge it by (`Cache-Tag`, `Surrogate-Key`). A request with a credential is
+     * always answered `private` — see `RestCache`. `tags` receives the answer as
+     * it goes on the wire.
+     */
+    readonly cache?: RestCache;
 }
 
 /**
@@ -1179,6 +1187,27 @@ export declare interface RestByteResponse {
     readonly headers?: Readonly<Record<string, string | ReadonlyArray<string>>>;
 }
 
+/**
+ * Caching for a GET route's successful (200) answers.
+ *
+ * An anonymous request's answer is `public` for `maxAge` seconds (`max-age`
+ * and `s-maxage`), `stale-while-revalidate` when set, and carries `tags` as
+ * `Cache-Tag` (comma-separated) and `Surrogate-Key` (space-separated) — the
+ * headers CDNs purge by. A request that carries a credential (`Authorization`
+ * or a cookie) gets `private, no-cache` and no tags, whatever is declared:
+ * what a key or a session may see must never land in a shared cache. Every
+ * such answer says `Vary: Authorization, Cookie`. Errors are not affected.
+ */
+export declare interface RestCache {
+    /** Seconds a cache may serve the answer without asking again. */
+    readonly maxAge: number;
+    /** Seconds after that a stale answer may still be served while the cache refetches. */
+    readonly staleWhileRevalidate?: number;
+    /** Purge tags from the answer as it goes on the wire, and the input.
+     *  A tag with whitespace or a comma is dropped (no header can carry it). */
+    readonly tags?: (output: unknown, input: unknown) => ReadonlyArray<string>;
+}
+
 export declare type RestDates = 'iso' | 'epoch-ms';
 
 export declare type RestEnvelope = 'none' | 'data' | 'jsonapi';
@@ -1270,6 +1299,11 @@ export declare interface RestGuardRejection {
     readonly message: string;
 }
 
+/** What a REST handler may return: the decoded output, a `response(...)` with
+ *  its own status and headers, an `sse(...)` stream, or `bytes(...)` for a
+ *  non-JSON body (a file, an export, an XML document). */
+export declare type RestHandlerResult<O> = O | RestResponse<O> | RestStreamResponse | RestByteResponse;
+
 export declare type RestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
 
 export declare type RestNaming = 'camelCase' | 'snake_case';
@@ -1333,7 +1367,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 | RestResponse<O>> | O | RestResponse<O>;
+    readonly handler: (input: I, ctx: RestRouteContext) => Promise<RestHandlerResult<O>> | RestHandlerResult<O>;
     readonly summary?: string;
     readonly description?: string;
     readonly example?: RestRouteExample;
@@ -1390,6 +1424,9 @@ export declare interface RestRouteDescriptor<I, O> {
      *  of the JSON), so it is correct across content-encodings — the
      *  transport's compression varies the bytes, not the representation. */
     readonly etag?: boolean;
+    /** GET only: how long a shared cache (a CDN) may keep a successful answer,
+     *  and the tags it can be purged by. See {@link RestCache}. */
+    readonly cache?: RestCache;
 }
 
 /** Intentional non-2xx REST control flow with an application-defined JSON