@voltro/protocol 0.80.0 → 0.82.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;
@@ -78,6 +78,72 @@ 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";
 }

package/dist/inspect.js

@@ -1,85 +1,119 @@
 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.String.pipe(e.filter((e) => Number.isFinite(Date.parse(e)))), o = e.String.pipe(e.minLength(1), e.maxLength(256)), s = e.Struct({
+	id: o,
+	name: o,
+	from: a,
+	to: a,
 	occurrences: e.Array(e.Number),
 	status: e.Literal("queued", "running", "completed", "interrupted"),
 	owner: e.NullOr(e.String),
-	createdAt: t,
-	updatedAt: t,
+	createdAt: a,
+	updatedAt: a,
 	cursor: e.Number,
 	activeIndex: e.NullOr(e.Number),
 	results: e.Array(e.Struct({
-		runId: n,
+		runId: o,
 		status: e.Literal("succeeded", "failed", "skipped", "missed")
 	})),
 	error: e.NullOr(e.String)
-}), i = e.Struct({
-	requestId: n,
-	name: n,
-	from: t,
-	to: t,
+}), c = e.Struct({
+	requestId: o,
+	name: o,
+	from: a,
+	to: a,
 	confirm: e.Boolean,
 	limit: e.Number.pipe(e.int(), e.between(1, 1e4))
-}), a = e.decodeUnknownSync(i), o = e.Union(e.Struct({
+}), l = e.decodeUnknownSync(c), u = e.Union(e.Struct({
 	kind: e.Literal("accepted"),
-	request: r
+	request: s
 }), e.Struct({
 	kind: e.Literal("refused"),
-	name: n,
+	name: o,
 	occurrences: e.Number,
 	reason: e.String
-})), s = class extends Error {
+})), d = 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([
+}, f = e.NonEmptyString.pipe(e.maxLength(1024), e.filter((e) => e.trim().length > 0 && !/[\u0000-\u001f\u007f]/.test(e))), p = e.Struct({
+	workflowName: f,
+	executionId: f
+}), m = p.fields, h = e.Union(e.Struct({
+	...m,
+	kind: e.Literal("not-observed")
+}), e.Struct({
+	...m,
+	kind: e.Literal("pending")
+}), e.Struct({
+	...m,
+	kind: e.Literal("delivery-failed")
+}), e.Struct({
+	...m,
+	kind: e.Literal("suspended")
+}), e.Struct({
+	...m,
+	kind: e.Literal("completed"),
+	outcome: e.Literal("succeeded", "failed", "cancelled")
+})), g = (e) => typeof e == "object" && e && !Array.isArray(e) ? e : void 0, _ = (e) => Array.isArray(e) && e.every((e) => g(e) !== void 0) ? e : void 0, v = (e) => typeof e == "number" && Number.isFinite(e) ? e : 0, y = /* @__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);
+]), b = (e) => {
+	let t = _(e);
+	return t?.every((e) => typeof e.name == "string" && y.has(String(e.type))) ? t : void 0;
+}, x = (e) => {
+	let t = g(e), n = g(t?.data), r = _(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: g(e.observation),
+		data: g(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: g(e.data)
+	})), o = (e) => a.reduce((t, n) => t + v(n.object?.[e]), 0), s = Math.max(...i.map((e) => v(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) => _(e.object?.records))) {
+		let e = a.flatMap((e) => _(e.object?.records).map((t) => ({
 			...t,
 			fields: {
-				...c(t.fields),
+				...g(t.fields),
 				"voltro.replica": e.replicaId
 			}
-		}))).sort((e, t) => u(e.ts) - u(t.ts));
-		p = {
-			...d,
+		}))).sort((e, t) => v(e.ts) - v(t.ts));
+		l = {
+			...c,
 			returned: e.length,
 			records: e
 		};
-	} else if (a.every((e) => l(e.object?.traces))) {
+	} else if (a.every((e) => _(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 _(t.object?.traces)) {
+			let r = String(n.traceId), i = (_(n.spans) ?? []).map((e) => ({
 				...e,
 				attributes: {
-					...c(e.attributes),
+					...g(e.attributes),
 					"voltro.replica": t.replicaId
 				}
 			})), a = e.get(r) ?? [];
@@ -89,7 +123,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) => _(e.spans) ?? []).sort((e, t) => v(e.startMs) - v(t.startMs)), n = [...e].sort((e, t) => v(e.startMs) - v(t.startMs))[0], r = Math.min(...e.map((e) => v(e.startMs))), i = Math.max(...e.map((e) => v(e.startMs) + v(e.durationMs)));
 			return {
 				...n,
 				startMs: r,
@@ -97,65 +131,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 + v(t.deliveryCount), 0) } : {},
+				...e.some((e) => e.lastDeliveryMs !== void 0) ? { lastDeliveryMs: Math.max(...e.map((e) => v(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) => _(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) => v(e.object?.windowMs))),
 		totalSamples: o("totalSamples"),
-		buckets: a.flatMap((e) => l(e.object?.buckets).map((t) => ({
+		buckets: a.flatMap((e) => _(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) => b(e.data))) l = i.flatMap((e) => b(e.data).map((t) => ({
 		...t,
 		labels: {
-			...c(t.labels),
+			...g(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) => b(e.object?.samples))) l = { samples: a.flatMap((e) => b(e.object?.samples).map((t) => ({
 		...t,
 		labels: {
-			...c(t.labels),
+			...g(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 {
+}, S = class extends Error {
 	name = "InvalidReplicaSelection";
-}, h = (e) => {
+}, C = (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 S("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 S("Replica IDs must be nonempty and contain no control characters.");
 		return {
 			mode: "selected",
 			replicaIds: [...new Set(n)].sort()
 		};
 	}
-}, g = (e, t) => {
+}, w = (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 S("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 C(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 { c as InspectBackfillInputSchema, s as InspectBackfillReceiptSchema, u as InspectBackfillResultSchema, h as InspectWorkflowExecutionObservationSchema, p as InspectWorkflowExecutionTargetSchema, i as InspectWorkflowQueuedStartObservationSchema, n as InspectWorkflowQueuedStartTargetSchema, S as InvalidReplicaSelection, d as ScheduleBackfillRequestConflict, l as decodeInspectBackfillInput, C as parseReplicaSelection, x as projectReplicaObservation, w 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 —
@@ -339,6 +339,14 @@ declare const Subject: Schema.Union<[Schema.Struct<{
     tenantId: typeof Schema.Null;
     scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
     metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["service"]>;
+    id: typeof Schema.String;
+    /** The calling app's name, as the callee lists it in `serviceCallers`. */
+    service: typeof Schema.String;
+    tenantId: typeof Schema.Null;
+    scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
+    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
 }>]>;
 
 declare type Subject = typeof Subject.Type;

package/dist/rest.d.ts

@@ -30,6 +30,9 @@ declare interface ActionProcedureDescriptor<Name extends string, Input extends S
      *  `openAccess: '<why>'`. Mutually exclusive with `guards`; together they are
      *  the only two shapes `security.defaultDeny` accepts. */
     readonly openAccess: string | undefined;
+    /** Only these apps of the project may call this procedure — see `service` on
+     *  the definer's options. Absent → the app's own clients call it. */
+    readonly service: ServiceSpec | undefined;
     /** Opt this action into a public REST endpoint (innovation/11). */
     readonly publicApi: PublicApiSpec | undefined;
     /** Opt this action into the auto-synthesized agent toolset (innovation/07). */
@@ -138,7 +141,7 @@ export declare const collectPublicApiRoutes: (entries: ReadonlyArray<PublicApiEn
  * because that is where the normalised decision lands, and because every
  * enforcement path reads the descriptor's array and nothing else.
  */
-declare type DeclaredAccess<Input = unknown> = ReadonlyArray<AnyGuardSpec<Input> | OpenAccessSpec>;
+declare type DeclaredAccess<Input = unknown> = ReadonlyArray<AnyGuardSpec<Input> | OpenAccessSpec | ServiceAccessSpec>;
 
 /** The `_tag` literals a descriptor's `error:` union declares (empty for none). */
 export declare const declaredErrorTags: (error: Schema.Schema.All | undefined) => ReadonlySet<string>;
@@ -178,15 +181,16 @@ export declare const deriveResource: (tag: string, spec: PublicApiSpec, descript
 
 /**
  * Dispatch a request across REST routes that SHARE a path. Every REST route
- * mounts as `*` and gates its own method, returning a precise 405 BEFORE any
- * side effect when the method isn't its own — so probing the group in order and
- * taking the FIRST non-405 result yields the route that owns the request's
- * method. This is what lets the standard GET + POST on one resource path
- * coexist: the runtime's rpc server (`rpcServer.ts`, started by both boot
- * paths) mounts ONE dispatcher per path (the underlying
- * router rejects two mounts on the same `(method, path)`). A single-route group
- * returns that route's result directly (its own 405 included); when no route in
- * the group owns the method, the last 405 stands.
+ * gates its own method, returning a precise 405 BEFORE any side effect when the
+ * method isn't its own — so probing the group in order and taking the FIRST
+ * non-405 result yields the route that owns the request's method. This is what
+ * lets the standard GET + POST on one resource path coexist: `rpcServer.ts` in
+ * `@voltro/runtime` mounts ONE dispatcher per
+ * path (the underlying router rejects two mounts on the same
+ * `(method, path)`). A single-route group returns that route's result directly
+ * (its own 405 included); when no route in the group owns the method, the last
+ * 405 stands — its `Allow` names every method the path serves, because
+ * `restRoutesToHttpRoutes` gives each route its path's full set.
  *
  * `group` must be non-empty (the serve pipeline only builds a dispatcher for a
  * path that has at least one route).
@@ -283,14 +287,24 @@ declare interface IdempotencyStore {
     /** Current record for (scope, key), or null. Read-side (inspect/dashboard). */
     readonly get: (scope: string, key: string) => Promise<IdempotencyRecord | null>;
     /**
-     * Atomically claim (scope, key) IF absent OR stale (older than `ttlMs`):
+     * Atomically claim (scope, key) IF absent OR stale — a COMPLETED record older
+     * than `ttlMs` (the replay window), or an IN-FLIGHT one whose lease
+     * (`inFlightLeaseMs`, renewed by the live handler) lapsed:
      * write a fresh `in_flight` row and return `'claimed'`. Otherwise return the
      * EXISTING (still-fresh) record. The atomicity here is the whole game — two
      * concurrent same-key requests both hit this, exactly one gets `'claimed'`,
      * the loser reads the winner's record. In SQL this is one
      * `INSERT … ON CONFLICT DO UPDATE … WHERE existing.createdAt < now - ttl`.
      */
-    readonly claim: (scope: string, key: string, now: number, ttlMs: number) => Promise<'claimed' | IdempotencyRecord>;
+    readonly claim: (scope: string, key: string, now: number, ttlMs: number, inFlightLeaseMs: number) => Promise<'claimed' | IdempotencyRecord>;
+    /**
+     * Extend a RUNNING claim's lease: bump its timestamp while it is still
+     * `in_flight` (a completed or released claim is left alone). The server calls
+     * it while the handler runs; a process that dies stops calling it, and its
+     * claim goes stale after `inFlightLeaseMs` instead of after the whole replay
+     * window.
+     */
+    readonly renew: (scope: string, key: string, now: number) => Promise<void>;
     /** Flip the claim to `completed` and store the response. */
     readonly complete: (scope: string, key: string, response: IdempotencyResponse, now: number) => Promise<void>;
     /** Drop the claim (handler errored → a retry may re-process). */
@@ -370,6 +384,9 @@ declare interface MutationProcedureDescriptor<Name extends string, Input extends
      *  `openAccess: '<why>'`. Mutually exclusive with `guards`; together they are
      *  the only two shapes `security.defaultDeny` accepts. */
     readonly openAccess: string | undefined;
+    /** Only these apps of the project may call this procedure — see `service` on
+     *  the definer's options. Absent → the app's own clients call it. */
+    readonly service: ServiceSpec | undefined;
     /** Opt this mutation into a public REST endpoint (innovation/11). */
     readonly publicApi: PublicApiSpec | undefined;
     /** Opt this mutation into the auto-synthesized agent toolset (innovation/07). */
@@ -423,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;
 }
@@ -504,11 +521,17 @@ declare interface PluginErrorSchema {
 
 /** A public raw-HTTP route a plugin serves on the framework listener. */
 declare interface PluginHttpRoute {
-    /** HTTP method, or `'*'` for any (the handler decides). PATCH/HEAD/OPTIONS
-     *  are first-class — the REST desugar used to mount `'*'` partly BECAUSE
-     *  this union lacked PATCH; that reason is gone (the `'*'` mount remains
-     *  for its other job: one dispatcher per shared path + a precise 405). */
+    /** HTTP method, or `'*'` for any (the handler decides). The server mounts the
+     *  path for exactly the methods its routes declare; `'*'` mounts it for every
+     *  method the router knows (34), so keep that for a route that really serves
+     *  them — see `answersOtherMethods` for one that only wants to refuse them. */
     readonly method: '*' | 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+    /** `true`: the handler gates its own method, so a request with a method the
+     *  path does not declare is still handed to it — to answer with a precise
+     *  `405` and `Allow` instead of the router's `404`. The path is still mounted
+     *  only for `method`. A REST route sets it. Without it, a route that declares
+     *  one method never sees another. */
+    readonly answersOtherMethods?: boolean | undefined;
     /** Absolute path, e.g. `/_voltro/storage`. Matched byte for byte: the
      *  router folds case and a trailing slash to FIND the route, the dispatcher
      *  then asks whether the request's path is one the route declared — so
@@ -776,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.
  */
@@ -963,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;
 }
 
 /**
@@ -1052,6 +1083,9 @@ declare interface QueryProcedureDescriptor<Name extends string, Input extends Sc
      *  `openAccess: '<why>'`. Mutually exclusive with `guards`; together they are
      *  the only two shapes `security.defaultDeny` accepts. */
     readonly openAccess: string | undefined;
+    /** Only these apps of the project may call this procedure — see `service` on
+     *  the definer's options. Absent → the app's own clients call it. */
+    readonly service: ServiceSpec | undefined;
     /** Opt this query into a public REST endpoint (innovation/11). */
     readonly publicApi: PublicApiSpec | undefined;
     /** Opt this query into the auto-synthesized agent toolset (innovation/07). */
@@ -1153,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';
@@ -1244,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';
@@ -1307,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;
@@ -1364,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
@@ -1490,6 +1553,37 @@ export declare const routeAcceptsPath: (route: {
     readonly match?: "prefix" | "exact" | undefined;
 }, path: string) => boolean;
 
+/**
+ * The runtime-erased form of a procedure's `service: { callers }` — "only these
+ * apps of the project may call this, and nobody else".
+ *
+ * A guard entry for the reason `OpenAccessSpec` is one: every enforcement path
+ * is handed the `guards` array and nothing else, so a decision that lived on a
+ * separate descriptor field would be enforced by the paths somebody remembered
+ * and skipped by the rest.
+ *
+ * It admits exactly a `service` subject whose name is listed. `admin:full` does
+ * NOT bypass it: a service procedure is a machine contract between two apps,
+ * and a browser session holding the admin scope is not one of the parties.
+ */
+declare interface ServiceAccessSpec {
+    /** The calling apps' names, as the callee declares them in `serviceCallers`.
+     *  Non-empty by construction — the definers refuse an empty list. */
+    readonly service: ReadonlyArray<string>;
+}
+
+/**
+ * A service procedure's declaration: which apps of the project may call it.
+ *
+ *     service: { callers: ['worker'] }
+ *
+ * The names are the CALLING apps' names as this app lists them in
+ * `serviceCallers` — the same name the caller's credential resolves to.
+ */
+declare interface ServiceSpec {
+    readonly callers: ReadonlyArray<string>;
+}
+
 /**
  * Build a streaming (Server-Sent Events) handler result. `subscribe` gets an
  * `emit` for one already-framed SSE chunk and MUST return an unsubscribe, which
@@ -1558,6 +1652,14 @@ declare const Subject: Schema.Union<[Schema.Struct<{
     tenantId: typeof Schema.Null;
     scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
     metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["service"]>;
+    id: typeof Schema.String;
+    /** The calling app's name, as the callee lists it in `serviceCallers`. */
+    service: typeof Schema.String;
+    tenantId: typeof Schema.Null;
+    scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
+    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
 }>]>;
 
 declare type Subject = typeof Subject.Type;