@voltro/protocol 0.70.0 → 0.71.0

package/dist/inspect.d.ts

@@ -0,0 +1,100 @@
+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 to: string;
+    readonly requestId: string;
+    readonly confirm: boolean;
+};
+
+export declare type InspectBackfillInput = typeof InspectBackfillInputSchema.Type;
+
+export declare const InspectBackfillInputSchema: Schema.Struct<{
+    requestId: Schema.filter<Schema.filter<typeof Schema.String>>;
+    name: Schema.filter<Schema.filter<typeof Schema.String>>;
+    from: Schema.filter<typeof Schema.String>;
+    to: Schema.filter<typeof Schema.String>;
+    confirm: typeof Schema.Boolean;
+    limit: Schema.filter<Schema.filter<typeof Schema.Number>>;
+}>;
+
+export declare type InspectBackfillReceipt = typeof InspectBackfillReceiptSchema.Type;
+
+export declare const InspectBackfillReceiptSchema: Schema.Struct<{
+    id: Schema.filter<Schema.filter<typeof Schema.String>>;
+    name: Schema.filter<Schema.filter<typeof Schema.String>>;
+    from: Schema.filter<typeof Schema.String>;
+    to: Schema.filter<typeof Schema.String>;
+    occurrences: Schema.Array$<typeof Schema.Number>;
+    status: Schema.Literal<["queued", "running", "completed", "interrupted"]>;
+    owner: Schema.NullOr<typeof Schema.String>;
+    createdAt: Schema.filter<typeof Schema.String>;
+    updatedAt: Schema.filter<typeof Schema.String>;
+    cursor: typeof Schema.Number;
+    activeIndex: Schema.NullOr<typeof Schema.Number>;
+    results: Schema.Array$<Schema.Struct<{
+        runId: Schema.filter<Schema.filter<typeof Schema.String>>;
+        status: Schema.Literal<["succeeded", "failed", "skipped", "missed"]>;
+    }>>;
+    error: Schema.NullOr<typeof Schema.String>;
+}>;
+
+export declare type InspectBackfillResult = typeof InspectBackfillResultSchema.Type;
+
+export declare const InspectBackfillResultSchema: Schema.Union<[Schema.Struct<{
+    kind: Schema.Literal<["accepted"]>;
+    request: Schema.Struct<{
+        id: Schema.filter<Schema.filter<typeof Schema.String>>;
+        name: Schema.filter<Schema.filter<typeof Schema.String>>;
+        from: Schema.filter<typeof Schema.String>;
+        to: Schema.filter<typeof Schema.String>;
+        occurrences: Schema.Array$<typeof Schema.Number>;
+        status: Schema.Literal<["queued", "running", "completed", "interrupted"]>;
+        owner: Schema.NullOr<typeof Schema.String>;
+        createdAt: Schema.filter<typeof Schema.String>;
+        updatedAt: Schema.filter<typeof Schema.String>;
+        cursor: typeof Schema.Number;
+        activeIndex: Schema.NullOr<typeof Schema.Number>;
+        results: Schema.Array$<Schema.Struct<{
+            runId: Schema.filter<Schema.filter<typeof Schema.String>>;
+            status: Schema.Literal<["succeeded", "failed", "skipped", "missed"]>;
+        }>>;
+        error: Schema.NullOr<typeof Schema.String>;
+    }>;
+}>, Schema.Struct<{
+    kind: Schema.Literal<["refused"]>;
+    name: Schema.filter<Schema.filter<typeof Schema.String>>;
+    occurrences: typeof Schema.Number;
+    reason: typeof Schema.String;
+}>]>;
+
+export declare type InspectReplicaSelection = {
+    readonly mode: 'all';
+} | {
+    readonly mode: 'selected';
+    readonly replicaIds: ReadonlyArray<string>;
+};
+
+export declare class InvalidReplicaSelection extends Error {
+    readonly name = "InvalidReplicaSelection";
+}
+
+/** Repeated parameters preserve IDs containing commas, spaces or punctuation. */
+export declare const parseReplicaSelection: (params: URLSearchParams) => InspectReplicaSelection | undefined;
+
+/** Preserve evidence about failed peers while projecting the composable inspect
+ * domains into their ordinary payload shape. Other domains require an explicit
+ * per-replica comparison; returning one responder as the aggregate is forbidden. */
+export declare const projectReplicaObservation: (value: unknown) => unknown;
+
+export declare class ScheduleBackfillRequestConflict extends Error {
+    readonly name = "ScheduleBackfillRequestConflict";
+}
+
+/** Canonical selection parameters; unrelated filters and pagination survive. */
+export declare const withReplicaSelection: (href: string, selection: InspectReplicaSelection) => string;
+
+export { }

package/dist/inspect.js

@@ -0,0 +1,160 @@
+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,
+	occurrences: e.Array(e.Number),
+	status: e.Literal("queued", "running", "completed", "interrupted"),
+	owner: e.NullOr(e.String),
+	createdAt: t,
+	updatedAt: t,
+	cursor: e.Number,
+	activeIndex: e.NullOr(e.Number),
+	results: e.Array(e.Struct({
+		runId: n,
+		status: e.Literal("succeeded", "failed", "skipped", "missed")
+	})),
+	error: e.NullOr(e.String)
+}), i = e.Struct({
+	requestId: n,
+	name: n,
+	from: t,
+	to: t,
+	confirm: e.Boolean,
+	limit: e.Number.pipe(e.int(), e.between(1, 1e4))
+}), a = e.decodeUnknownSync(i), o = e.Union(e.Struct({
+	kind: e.Literal("accepted"),
+	request: r
+}), e.Struct({
+	kind: e.Literal("refused"),
+	name: n,
+	occurrences: e.Number,
+	reason: e.String
+})), s = 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([
+	"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);
+	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
+	}));
+	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 = {
+		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) => ({
+			...t,
+			fields: {
+				...c(t.fields),
+				"voltro.replica": e.replicaId
+			}
+		}))).sort((e, t) => u(e.ts) - u(t.ts));
+		p = {
+			...d,
+			returned: e.length,
+			records: e
+		};
+	} else if (a.every((e) => l(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) => ({
+				...e,
+				attributes: {
+					...c(e.attributes),
+					"voltro.replica": t.replicaId
+				}
+			})), a = e.get(r) ?? [];
+			a.push({
+				...n,
+				spans: i
+			}), 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)));
+			return {
+				...n,
+				startMs: r,
+				durationMs: Math.max(0, i - r),
+				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))) } : {}
+			};
+		}).sort((e, t) => t.startMs - e.startMs);
+		p = {
+			...d,
+			returned: t.length,
+			traces: t
+		};
+	} else if (a.every((e) => l(e.object?.buckets) && typeof e.object?.windowMs == "number")) p = {
+		capturedAt: s,
+		windowMs: Math.max(...a.map((e) => u(e.object?.windowMs))),
+		totalSamples: o("totalSamples"),
+		buckets: a.flatMap((e) => l(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) => ({
+		...t,
+		labels: {
+			...c(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) => ({
+		...t,
+		labels: {
+			...c(t.labels),
+			voltro_replica: e.replicaId
+		}
+	}))) };
+	else throw Error("This view must compare observations per replica; its values cannot be safely combined.");
+	return {
+		...t,
+		data: p
+	};
+}, m = class extends Error {
+	name = "InvalidReplicaSelection";
+}, h = (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[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.");
+		return {
+			mode: "selected",
+			replicaIds: [...new Set(n)].sort()
+		};
+	}
+}, g = (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.");
+		for (let e of [...new Set(t.replicaIds)].sort()) s.append("replica", e);
+	}
+	return h(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 };

package/dist/jwt.d.ts

@@ -305,6 +305,11 @@ declare const Subject: Schema.Union<[Schema.Struct<{
     type: Schema.Literal<["serviceAccount"]>;
     id: typeof Schema.String;
     tenantId: typeof Schema.String;
+    /** Application actor used for audit columns; null means machine work with
+     * no application actor. Identity only, never a permission grant. */
+    auditActorId: Schema.optionalWith<Schema.NullOr<typeof Schema.String>, {
+        exact: true;
+    }>;
     scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
     metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
 }>, Schema.Struct<{

package/dist/rest.d.ts

@@ -159,11 +159,22 @@ declare interface DeleteTarget<Input = unknown> extends NestedTargetFields<Input
 }
 
 /** query→GET, mutation/action→POST, unless the spec overrides. */
-export declare const derivePublicMethod: (kind: PublicApiDescriptor["kind"], spec: PublicApiSpec) => RestMethod;
+export declare const derivePublicMethod: (kind: PublicApiDescriptor["kind"], spec: PublicApiSpec, descriptor?: ResourceDescriptorFacts) => RestMethod;
 
 /** `/<version>/<tag-with-dots-as-slashes>` unless the spec gives an explicit
- *  path. `orders.create` @ v1 → `/v1/orders/create`. */
-export declare const derivePublicPath: (tag: string, spec: PublicApiSpec) => string;
+ *  path, or `resource` derives one. `orders.create` @ v1 → `/v1/orders/create`. */
+export declare const derivePublicPath: (tag: string, spec: PublicApiSpec, descriptor?: ResourceDescriptorFacts) => string;
+
+/**
+ * `publicApi.resource`: method and path from the resource, the descriptor's
+ * kind and target, and whether the input identifies one row — the convention
+ * `crud.*` already follows, so a surface of hundreds of projections is not
+ * hundreds of hand-written paths.
+ */
+export declare const deriveResource: (tag: string, spec: PublicApiSpec, descriptor: ResourceDescriptorFacts) => {
+    readonly method: RestMethod;
+    readonly path: string;
+};
 
 /**
  * Dispatch a request across REST routes that SHARE a path. Every REST route
@@ -741,7 +752,7 @@ declare interface PluginHttpRouteStream {
  */
 declare interface PolicyGuardSpec<Input = unknown> {
     /** The action to authorize, as named in the resource policy's `actions`. */
-    readonly action: string;
+    readonly action: string | ((input: Input) => string);
     /** Which registered resource policy governs the check. */
     readonly resourceType: string;
     /** PURE `input → resource id`. Returning undefined DENIES — an unidentifiable
@@ -771,6 +782,26 @@ export declare const problemTypeOf: (tag: string) => string;
  */
 export declare const projectedFailure: (err: unknown, descriptor: PublicApiDescriptor, spec: PublicApiSpec, pluginErrors?: ReadonlyArray<PluginErrorSchema>) => unknown;
 
+/** The generated TypeScript client, as the app declares it. */
+export declare interface PublicApiClientConfig {
+    /** The npm package name. Default `@app/api-client`. */
+    readonly package?: string;
+    /** Where the package is written, relative to the app root. Default `sdk/typescript`. */
+    readonly out?: string;
+    /** `'plain'` — the Promise client, no Effect anywhere; `'effect'` — the
+     *  Effect service; `'both'` — `.` plain and `./effect` Effect, with `effect`
+     *  an optional peer. Default `'both'`. */
+    readonly flavor?: 'plain' | 'effect' | 'both';
+    /** The package's `license` field (an SPDX id). */
+    readonly license?: string;
+    /** The package's version. Default `0.1.0`. */
+    readonly packageVersion?: string;
+    /** Generate for ONE API version (`'v2'`). */
+    readonly apiVersion?: string;
+    /** The client's default base URL. */
+    readonly baseUrl?: string;
+}
+
 /** A descriptor kind that can be projected to REST (streams are not, in v1). */
 export declare type PublicApiDescriptor = QueryProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All> | MutationProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All> | ActionProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All>;
 
@@ -802,6 +833,28 @@ export declare interface PublicApiProfileConfig {
     readonly cursorParam?: string;
     readonly naming?: RestNaming;
     readonly etag?: boolean;
+    /** `'required'`: `voltro doctor` reports a projection without a
+     *  `description` and an input/output field without a `description`
+     *  annotation — so a new projection does not reach the surface without text.
+     *  Default `'optional'`. */
+    readonly docs?: 'required' | 'optional';
+    /**
+     * Files `voltro dev` writes beside `rpcGroup.generated.ts` on every boot, from
+     * the mounted surface: `'openapi'` (`openapi.generated.json`) and the
+     * collections — `'postman'`, `'bruno'`, `'insomnia'`, `'hoppscotch'` — as
+     * committed, generated files, so a review diff shows the surface change and
+     * a client imported once cannot drift; `'typescript'` keeps the generated
+     * client package (`client`) written the same way. Off by default.
+     */
+    readonly artifacts?: ReadonlyArray<'openapi' | 'postman' | 'bruno' | 'insomnia' | 'hoppscotch' | 'typescript'>;
+    /**
+     * The app's decision about its generated TypeScript client — what
+     * `voltro build api --target typescript` (and `voltro api-client build`)
+     * produces without flags, and what `voltro dev` keeps written when
+     * `artifacts` names `'typescript'`. `voltro api-client set …` writes this
+     * block; a flag on the command line overrides a field for one run.
+     */
+    readonly client?: PublicApiClientConfig;
 }
 
 export declare type PublicApiProfileName = 'rpc' | 'standard' | 'jsonapi';
@@ -836,6 +889,18 @@ declare interface PublicApiSpec {
     readonly method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
     /** Derived from the tag + version when omitted: `/<version>/<tag-as-path>`. */
     readonly path?: string;
+    /**
+     * Derive method and path from the resource instead of writing them — the
+     * convention `crud.*` already follows, opt-in per descriptor. `'teams'` on a
+     * query whose input carries `teamId` or `id` → `GET /v1/teams/{teamId}`,
+     * without one → `GET /v1/teams`; on a mutation whose `target.op` is
+     * `insert` → `POST /v1/teams`, `update` → `PATCH /v1/teams/{teamId}`,
+     * `delete` → `DELETE /v1/teams/{teamId}`; an action, or a mutation without
+     * a target, → `POST /v1/teams/{teamId}/<verb>` (the tag's last segment) when
+     * the input carries the id, else `POST /v1/teams/<verb>`. An explicit
+     * `method` or `path` wins over the derivation.
+     */
+    readonly resource?: string;
     /** Path version segment; multiple versions coexist as separate descriptors. */
     readonly version?: string;
     /** Additional API-key scopes required ON TOP of the handler's RBAC. */
@@ -912,6 +977,16 @@ export declare type PublicApiSubscribe = (input: unknown, ctx: RestRouteContext,
     readonly [k: string]: unknown;
 }) => void) => () => void;
 
+/**
+ * The digest of a public surface: every projection's facts (tag, method, path,
+ * parameters, version, security, the typed errors and their statuses) and the
+ * SHAPE of its wire schemas, in tag order. The OpenAPI document publishes it as
+ * `x-voltro-surface-digest`, a generated client carries the one it was built
+ * from, and `voltro check --public-api --against` compares the two — so one
+ * number says whether a consumer's client still describes the API it calls.
+ */
+export declare const publicSurfaceDigest: (routes: ReadonlyArray<RestRouteDescriptor<any, any>>) => string;
+
 /**
  * Server-side snapshot caching for a query (see `defineQuery`). When set,
  * the dispatcher caches the initial snapshot result and auto-invalidates it
@@ -1042,6 +1117,19 @@ export declare const requireScope: (scope: string) => RestGuard;
  */
 export declare const resolveRestFormat: (config: PublicApiProfileConfig | undefined, override?: Partial<PublicApiProfileConfig> | undefined) => RestFormat;
 
+/** What `resource` derivation reads off a descriptor. */
+export declare interface ResourceDescriptorFacts {
+    readonly kind: 'query' | 'mutation' | 'action' | 'stream';
+    readonly input?: unknown;
+    readonly target?: {
+        readonly op?: string;
+    } | undefined;
+}
+
+/** The input field that identifies one row of `resource`: `<singular>Id`,
+ *  then `id`; `undefined` when the input names neither (a list, a create). */
+export declare const resourceIdField: (resource: string, input: unknown) => string | undefined;
+
 export declare const response: <O>(body: O, options?: {
     readonly status?: number;
     readonly headers?: Readonly<Record<string, string | ReadonlyArray<string>>>;
@@ -1305,6 +1393,9 @@ export declare interface RestRouteProjection {
     readonly kind: 'query' | 'mutation' | 'action';
     readonly version: string;
     readonly security: 'required' | 'optional' | 'none';
+    /** `publicApi.idempotent` — the route honours `Idempotency-Key` (under the
+     *  app's idempotency binding); a client sends one per attempt. */
+    readonly idempotent: boolean;
     readonly input: Schema.Schema.All;
     /** The wire names of the input fields bound from the path. */
     readonly pathParams: ReadonlyArray<string>;
@@ -1382,8 +1473,9 @@ export declare interface RestStreamResponse {
 export declare const restViewSchema: (schema: Schema.Schema.All, format: RestFormat) => Schema.Schema.All;
 
 /**
- * Whether `path` is one the route declared. The router matches case-folded and
- * ignores a trailing slash; the dispatcher asks this, byte for byte: a literal
+ * Whether `path` is one the route declared. The underlying router folds case
+ * and trailing slashes when selecting candidates; this dispatcher deliberately
+ * rejects those undeclared aliases. It checks byte for byte: a literal
  * segment must be equal, a `:name` segment takes one non-empty segment, and
  * beyond the declared segments a `'prefix'` route (the default) owns any
  * sub-path while an `'exact'` route owns nothing. A trailing slash alone is
@@ -1429,6 +1521,11 @@ declare const Subject: Schema.Union<[Schema.Struct<{
     type: Schema.Literal<["serviceAccount"]>;
     id: typeof Schema.String;
     tenantId: typeof Schema.String;
+    /** Application actor used for audit columns; null means machine work with
+     * no application actor. Identity only, never a permission grant. */
+    auditActorId: Schema.optionalWith<Schema.NullOr<typeof Schema.String>, {
+        exact: true;
+    }>;
     scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
     metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
 }>, Schema.Struct<{
@@ -1532,4 +1629,12 @@ declare interface UpdateTarget<Input = unknown, Row = unknown, Item = Record<str
     readonly shapeItem?: ((input: Input, current: Item) => Item) | undefined;
 }
 
+export declare const wireExample: (example: {
+    readonly request?: unknown;
+    readonly response?: unknown;
+}, wireInput: Schema.Schema.All, wireOutput: Schema.Schema.All) => {
+    readonly request?: unknown;
+    readonly response?: unknown;
+};
+
 export { }