@stigmer/server 3.14.0-dev.20260910084630

package/src/pipeline/steps/persist.ts

@@ -0,0 +1,41 @@
+/**
+ * Persist — ports steps/persist.go: saves newState through the store
+ * (metadata.id must be set by an earlier step).
+ */
+import type { DescMessage } from "@bufbuild/protobuf";
+
+import type { Store } from "../../store/interface.js";
+import { internalError } from "../errors.js";
+import type { PipelineStep } from "../pipeline.js";
+import type { RequestContext } from "../request-context.js";
+import { metadataOf } from "./shapes.js";
+
+export function newPersistStep<Desc extends DescMessage>(
+  store: Store,
+): PipelineStep<Desc> {
+  return {
+    name: "Persist",
+    async execute(ctx: RequestContext<Desc>): Promise<void> {
+      const metadata = metadataOf(ctx.newState);
+      if (metadata === undefined) {
+        throw internalError(new Error("resource metadata is nil"), "persist");
+      }
+      if (metadata.id === "") {
+        throw internalError(
+          new Error("resource ID is empty, cannot persist"),
+          "persist",
+        );
+      }
+      try {
+        await store.saveResource(
+          ctx.apiResourceKind,
+          metadata.id,
+          ctx.schema,
+          ctx.newState,
+        );
+      } catch (error) {
+        throw internalError(error, "failed to save resource to store");
+      }
+    },
+  };
+}

package/src/pipeline/steps/references.ts

@@ -0,0 +1,172 @@
+/**
+ * NormalizeReferences + ValidateReferences — port
+ * steps/normalize_references.go and steps/validate_references.go, sharing
+ * one spec walker (as the Go files share theirs).
+ *
+ * NormalizeReferences fills EMPTY org fields in ApiResourceReference
+ * messages inside the spec from the resource's own metadata.org, so stored
+ * references are absolute; explicit orgs (cross-org refs) are preserved.
+ * Only the spec is walked — status is system-generated and already
+ * absolute. Runs after BuildNewState/BuildUpdateState, before Persist.
+ *
+ * ValidateReferences verifies spec references point at existing resources
+ * — strict FAILED_PRECONDITION for missing MCP servers (an agent whose MCP
+ * server is missing cannot execute its declared tools). Runs AFTER
+ * NormalizeReferences so orgs are resolved.
+ */
+import type { DescMessage } from "@bufbuild/protobuf";
+import { reflect } from "@bufbuild/protobuf/reflect";
+import type { ReflectMessage } from "@bufbuild/protobuf/reflect";
+
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import type { Store } from "../../store/interface.js";
+import { failedPreconditionError, internalError } from "../errors.js";
+import type { PipelineStep } from "../pipeline.js";
+import type { RequestContext } from "../request-context.js";
+import { findResourceBySlug } from "./helpers.js";
+import { messageFieldByName, metadataOf } from "./shapes.js";
+
+const API_RESOURCE_REFERENCE_TYPE =
+  "ai.stigmer.commons.apiresource.ApiResourceReference";
+
+export function newNormalizeReferencesStep<Desc extends DescMessage>(): PipelineStep<Desc> {
+  return {
+    name: "NormalizeReferences",
+    execute(ctx: RequestContext<Desc>): void {
+      const metadata = metadataOf(ctx.newState);
+      if (metadata === undefined) {
+        throw internalError(new Error("resource metadata is nil"), "normalize references");
+      }
+      // No org to resolve from — skip silently; required-org validation is
+      // the validation step's responsibility, not this one's.
+      if (metadata.org === "") {
+        return;
+      }
+      forEachSpecReference(ctx.schema, ctx.newState, (ref) => {
+        const orgField = ref.fields.find((f) => f.name === "org");
+        if (orgField !== undefined && (ref.get(orgField) as string) === "") {
+          ref.set(orgField, metadata.org);
+        }
+      });
+    },
+  };
+}
+
+export function newValidateReferencesStep<Desc extends DescMessage>(
+  store: Store,
+): PipelineStep<Desc> {
+  return {
+    name: "ValidateReferences",
+    async execute(ctx: RequestContext<Desc>): Promise<void> {
+      const refs: Array<{ kind: number; slug: string; org: string }> = [];
+      forEachSpecReference(ctx.schema, ctx.newState, (ref) => {
+        refs.push({
+          kind: numberField(ref, "kind"),
+          slug: stringField(ref, "slug"),
+          org: stringField(ref, "org"),
+        });
+      });
+
+      const missingMcpServers: string[] = [];
+      for (const ref of refs) {
+        if (ref.slug === "") {
+          continue;
+        }
+        // Per-kind validation, exactly Go's switch: only mcp_server today.
+        if (ref.kind === ApiResourceKind.mcp_server) {
+          const found = await findResourceBySlug(
+            store,
+            ApiResourceKind.mcp_server,
+            McpServerSchema,
+            ref.slug,
+            ref.org,
+          );
+          if (found === undefined) {
+            missingMcpServers.push(`'${ref.slug}' (org: ${ref.org})`);
+          }
+        }
+      }
+
+      if (missingMcpServers.length > 0) {
+        throw failedPreconditionError(
+          `referenced MCP server(s) not found: ${missingMcpServers.join(", ")}. ` +
+            "Verify the slug and org are correct. " +
+            "Use 'stigmer get mcp-servers' to list available MCP servers.",
+        );
+      }
+    },
+  };
+}
+
+/**
+ * Walks the resource's spec and invokes fn on every ApiResourceReference
+ * (singular, repeated, and map-valued message fields, recursively) —
+ * the shared traversal behind both steps (Go walkAndResolveOrg /
+ * walkAndCollectRefs). Mutations through the ReflectMessage write through.
+ */
+function forEachSpecReference(
+  schema: DescMessage,
+  msg: Parameters<typeof reflect>[1],
+  fn: (ref: ReflectMessage) => void,
+): void {
+  const root = reflect(schema, msg);
+  const specField = messageFieldByName(root, "spec");
+  if (specField === undefined || !root.isSet(specField)) {
+    return;
+  }
+  walk(root.get(specField), fn);
+}
+
+function walk(msg: ReflectMessage, fn: (ref: ReflectMessage) => void): void {
+  for (const field of msg.fields) {
+    if (field.fieldKind === "list") {
+      if (field.listKind !== "message") {
+        continue;
+      }
+      for (const item of msg.get(field)) {
+        visit(item as ReflectMessage, fn);
+      }
+    } else if (field.fieldKind === "map") {
+      if (field.mapKind !== "message") {
+        continue;
+      }
+      const map = msg.get(field);
+      for (const [, value] of map) {
+        visit(value as ReflectMessage, fn);
+      }
+    } else if (field.fieldKind === "message") {
+      if (!msg.isSet(field)) {
+        continue;
+      }
+      visit(msg.get(field), fn);
+    }
+  }
+}
+
+function visit(sub: ReflectMessage, fn: (ref: ReflectMessage) => void): void {
+  if (sub.desc.typeName === API_RESOURCE_REFERENCE_TYPE) {
+    fn(sub);
+  } else {
+    walk(sub, fn);
+  }
+}
+
+function stringField(msg: ReflectMessage, name: string): string {
+  const field = msg.fields.find((f) => f.name === name);
+  if (field === undefined) {
+    return "";
+  }
+  const value = msg.get(field);
+  return typeof value === "string" ? value : "";
+}
+
+function numberField(msg: ReflectMessage, name: string): number {
+  const field = msg.fields.find((f) => f.name === name);
+  if (field === undefined) {
+    return 0;
+  }
+  const value = msg.get(field);
+  return typeof value === "number" ? value : 0;
+}

package/src/pipeline/steps/secret-cleanup.ts

@@ -0,0 +1,109 @@
+/**
+ * Secret backing-state cleanup — the OSS half of the Java
+ * SecretValueCleanup contract (secrets-vault migration; wired here by
+ * convergence 20260830.04 Stage 3, gate ruling Q7). When a resource
+ * carrying sealed secrets is deleted — or a secret-bearing key is
+ * dropped by an update — the stored ciphertext's EXTERNAL backing state
+ * must be destroyed: for enc:v3 values that is a KV entry in the vault;
+ * for enc:v1/v2 values (the ciphertext IS the stored value), plaintext,
+ * and the ***REDACTED*** marker, SecretService.delete is a no-op by
+ * construction. Under the OSS default codec set (v1 only) this module
+ * therefore never changes observable behavior — the conformance rosters
+ * pin that.
+ *
+ * Failure semantics (Java parity; the CleanupIamPolicies discipline):
+ * best-effort, AFTER the store write. The row is already gone or
+ * updated, so a destroy failure must never fail the request — each
+ * failure logs ERROR with the resource identity and the pass continues.
+ * The cloud edition additionally counts sweep-side destroy failures
+ * (stigmer.encryption.cleanup.failures); the OSS delete sites log only
+ * (Stage-3 gate ruling G4 — an accepted, disclosed divergence that is
+ * moot until a composition writes enc:v3).
+ */
+import type { DescMessage, MessageShape } from "@bufbuild/protobuf";
+
+import type { Logger } from "../../boot/logger.js";
+import type { SecretService } from "../../encryption/encryption.js";
+import { getKindName } from "../apiresource-meta.js";
+import type { PipelineStep } from "../pipeline.js";
+import type { RequestContext } from "../request-context.js";
+import { EXISTING_RESOURCE_KEY } from "./load-existing.js";
+import type { HasMetadataShape } from "./shapes.js";
+
+/**
+ * Destroys the external backing state of each stored secret value,
+ * best-effort: one failure logs ERROR (with the caller's identifying
+ * fields) and never interrupts the rest. Blank values are skipped — the
+ * facade would no-op them anyway, and skipping keeps the logs honest.
+ *
+ * Exported for the write-boundary steps that must capture their old
+ * values before mutating (environment removeVariables) and for the
+ * domain steps that destroy on a key diff rather than a delete.
+ */
+export async function destroySecretBackingState(
+  secretService: SecretService,
+  logger: Logger,
+  fields: Record<string, unknown>,
+  storedValues: readonly string[],
+): Promise<void> {
+  for (const storedValue of storedValues) {
+    if (storedValue === "") {
+      continue;
+    }
+    try {
+      await secretService.delete(storedValue);
+    } catch (error) {
+      // The DB write already succeeded — an orphaned external entry is
+      // the recoverable outcome (the vault retains it; the convergence
+      // sweep's census keeps it visible). Never the request's failure.
+      logger.error(
+        "secret backing-state destruction failed after persist — external state may be orphaned",
+        {
+          ...fields,
+          error: error instanceof Error ? error.message : String(error),
+        },
+      );
+    }
+  }
+}
+
+/**
+ * DestroySecretBackingState — after the store delete in every delete
+ * chain whose kind carries sealed secrets (environment, oauthapp,
+ * channelapp; the OAuth-managed environment lane rides the environment
+ * chain through the in-process client). Reads the doomed resource from
+ * EXISTING_RESOURCE_KEY (seeded by LoadExistingForDelete); the
+ * per-domain extractor names which spec fields hold sealed values.
+ */
+export function newDestroySecretBackingStateStep<
+  InputDesc extends DescMessage,
+  ResourceDesc extends DescMessage,
+>(
+  secretService: SecretService,
+  logger: Logger,
+  extractSecretValues: (
+    resource: MessageShape<ResourceDesc>,
+  ) => readonly string[],
+): PipelineStep<InputDesc> {
+  return {
+    name: "DestroySecretBackingState",
+    async execute(ctx: RequestContext<InputDesc>): Promise<void> {
+      const deleted = ctx.get(EXISTING_RESOURCE_KEY) as
+        | MessageShape<ResourceDesc>
+        | undefined;
+      if (deleted === undefined) {
+        return;
+      }
+      const metadata = (deleted as unknown as HasMetadataShape).metadata;
+      await destroySecretBackingState(
+        secretService,
+        logger,
+        {
+          kind: getKindName(ctx.apiResourceKind),
+          resourceId: metadata?.id ?? "",
+        },
+        extractSecretValues(deleted),
+      );
+    },
+  };
+}

package/src/pipeline/steps/server-stamped-reserved-labels.ts

@@ -0,0 +1,56 @@
+/**
+ * ServerStampedReservedLabels — the per-request record of reserved
+ * `stigmer.ai/*` label keys that pipeline steps vouched for server-side
+ * (the Java ServerStampedReservedLabels port, cloud#386; parity entry
+ * 20260830.05).
+ *
+ * Some lanes legitimately carry reserved labels the client "sent": the
+ * workflow runner's CallAgent activity stamps the lineage pair
+ * (`stigmer.ai/workflow-execution-id`, `stigmer.ai/workflow-task`) on
+ * every child execution it creates. To GuardReservedLabels, which diffs
+ * the built state against the stored one, those stamps are
+ * indistinguishable from client mutations. A step that has made the
+ * trust decision for specific keys records EXACTLY those keys here, and
+ * the guard exempts exactly them — everything else in the namespace
+ * stays operator-only, so a client smuggling a different reserved key
+ * into the same request is still rejected.
+ *
+ * The record lives in the request context's metadata map: only server
+ * code can reach it, and it never survives the request (the same
+ * request-scoped posture as Java's gRPC Context key).
+ */
+import type { DescMessage } from "@bufbuild/protobuf";
+
+import type { RequestContext } from "../request-context.js";
+
+/** The context-metadata key carrying the vouched key set. */
+const STAMPED_KEYS_CONTEXT_KEY = "serverStampedReservedLabels";
+
+/**
+ * Records reserved label keys the calling step vouched for on this
+ * request. Call immediately next to the decision that vouches them, so
+ * the record and the decision cannot drift apart.
+ */
+export function recordServerStampedReservedLabels<Desc extends DescMessage>(
+  ctx: RequestContext<Desc>,
+  ...keys: ReadonlyArray<string>
+): void {
+  const existing = ctx.get(STAMPED_KEYS_CONTEXT_KEY);
+  const stamped = existing instanceof Set ? (existing as Set<string>) : new Set<string>();
+  for (const key of keys) {
+    stamped.add(key);
+  }
+  ctx.set(STAMPED_KEYS_CONTEXT_KEY, stamped);
+}
+
+/**
+ * The reserved label keys server-side steps vouched for on this request
+ * so far — GuardReservedLabels' exemption set. Empty when nothing was
+ * recorded (an empty answer only narrows what passes).
+ */
+export function serverStampedReservedLabels<Desc extends DescMessage>(
+  ctx: RequestContext<Desc>,
+): ReadonlySet<string> {
+  const stamped = ctx.get(STAMPED_KEYS_CONTEXT_KEY);
+  return stamped instanceof Set ? (stamped as Set<string>) : new Set<string>();
+}

package/src/pipeline/steps/shapes.ts

@@ -0,0 +1,102 @@
+/**
+ * Resource shape access — ports steps/interfaces.go (HasMetadata,
+ * HasValue, the status reflection helpers).
+ *
+ * Where Go needed protoreflect to reach metadata/status generically (its
+ * generated types are concrete structs), protobuf-es messages are plain
+ * objects sharing the SAME generated ApiResourceMetadata type — structural
+ * access is the idiomatic equivalent, not a shortcut. Reflection remains
+ * only where a message must be CREATED generically (a kind-specific status
+ * message needs its schema, which only the resource's descriptor knows).
+ */
+import { reflect } from "@bufbuild/protobuf/reflect";
+import type { ReflectMessage } from "@bufbuild/protobuf/reflect";
+import type { DescField, DescMessage, Message } from "@bufbuild/protobuf";
+
+import type { ApiResourceMetadata } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+
+/** Go HasMetadata: every API resource carries metadata of this one type. */
+export interface HasMetadataShape {
+  metadata?: ApiResourceMetadata;
+}
+
+/** Go HasValue / HasIdValue: ID-wrapper inputs (AgentId, OrganizationId, …). */
+export interface HasValueShape {
+  value: string;
+}
+
+/**
+ * The resource's metadata, or undefined when the message has none set.
+ * (Go's HasMetadata type assertion + GetMetadata nil-check collapsed.)
+ */
+export function metadataOf(msg: Message): ApiResourceMetadata | undefined {
+  return (msg as unknown as HasMetadataShape).metadata;
+}
+
+/** The ID-wrapper's value ("" when absent) — Go HasValue.GetValue(). */
+export function idValueOf(msg: Message): string {
+  const value = (msg as unknown as Partial<HasValueShape>).value;
+  return typeof value === "string" ? value : "";
+}
+
+/** A message-typed field, statically narrowed so get()/set() type-check. */
+export type MessageDescField = Extract<DescField, { fieldKind: "message" }>;
+
+/**
+ * Finds a singular message field by proto name with the narrowing TS needs
+ * to give ReflectMessage out of get() — the reflection idiom every helper
+ * in this library shares.
+ */
+export function messageFieldByName(
+  msg: ReflectMessage,
+  name: string,
+): MessageDescField | undefined {
+  const field = msg.fields.find((f) => f.name === name);
+  return field !== undefined && field.fieldKind === "message"
+    ? field
+    : undefined;
+}
+
+/**
+ * The resource's status as a write-through reflection wrapper, or
+ * undefined when the message has no status FIELD or the field is unset —
+ * Go getStatusField.
+ */
+export function getStatusField(
+  schema: DescMessage,
+  msg: Message,
+): ReflectMessage | undefined {
+  const root = reflect(schema, msg);
+  const field = messageFieldByName(root, "status");
+  if (field === undefined || !root.isSet(field)) {
+    return undefined;
+  }
+  return root.get(field);
+}
+
+/**
+ * The resource's status, created and attached when absent — Go
+ * getOrCreateStatusField. Returns undefined only when the message has no
+ * status field at all (a no-op for such kinds, as in Go).
+ */
+export function getOrCreateStatusField(
+  schema: DescMessage,
+  msg: Message,
+): ReflectMessage | undefined {
+  const root = reflect(schema, msg);
+  const field = messageFieldByName(root, "status");
+  if (field === undefined) {
+    return undefined;
+  }
+  if (!root.isSet(field)) {
+    root.set(field, reflect(field.message));
+  }
+  return root.get(field);
+}
+
+/** Whether the message's schema declares a status field — Go hasStatusField. */
+export function hasStatusField(schema: DescMessage): boolean {
+  return schema.fields.some(
+    (f) => f.name === "status" && f.fieldKind === "message",
+  );
+}

package/src/pipeline/steps/slug.ts

@@ -0,0 +1,48 @@
+/**
+ * ResolveSlug — ports steps/slug.go. Derives a URL-safe slug from
+ * metadata.name; idempotent when the slug is already set. NO length
+ * truncation, deliberately: truncation created silent collisions between
+ * different names, and the generator matches the cloud Java
+ * ApiRequestResourceSlugGenerator so both editions derive identical slugs
+ * (dots are namespace separators → hyphens, e.g. "platform.sara" →
+ * "platform-sara").
+ */
+import type { DescMessage } from "@bufbuild/protobuf";
+
+import { internalError, invalidArgumentError } from "../errors.js";
+import type { PipelineStep } from "../pipeline.js";
+import type { RequestContext } from "../request-context.js";
+import { metadataOf } from "./shapes.js";
+
+export function newResolveSlugStep<Desc extends DescMessage>(): PipelineStep<Desc> {
+  return {
+    name: "ResolveSlug",
+    execute(ctx: RequestContext<Desc>): void {
+      const metadata = metadataOf(ctx.newState);
+      if (metadata === undefined) {
+        // A server-side programming error, not bad client input (Go).
+        throw internalError(new Error("resource metadata is nil"), "slug resolution");
+      }
+      if (metadata.slug !== "") {
+        return; // already set — idempotent
+      }
+      if (metadata.name === "") {
+        // Name and slug both empty IS bad client input.
+        throw invalidArgumentError("resource name is required");
+      }
+      metadata.slug = generateSlug(metadata.name);
+    },
+  };
+}
+
+/**
+ * Go GenerateSlug: lowercase → spaces/dots to hyphens → strip
+ * non-[a-z0-9- ] → collapse hyphens → trim hyphens. No truncation.
+ */
+export function generateSlug(name: string): string {
+  let slug = name.toLowerCase();
+  slug = slug.replaceAll(" ", "-").replaceAll(".", "-");
+  slug = slug.replace(/[^a-z0-9\- ]/g, "");
+  slug = slug.replace(/-{2,}/g, "-");
+  return slug.replace(/^-+|-+$/g, "");
+}

package/src/pipeline/steps/validate-visibility.ts

@@ -0,0 +1,93 @@
+/**
+ * ValidateVisibility(+Update) — port steps/validate_visibility.go.
+ * Fail-fast rejection of visibility levels the kind does not support,
+ * BEFORE any state is built — cloud-identical INVALID_ARGUMENT copy, so
+ * clients see one contract across editions.
+ *
+ * Create-only by design: plain updates preserve stored visibility
+ * unconditionally (oss#573), so updateVisibility is the only other door
+ * and ValidateVisibilityUpdate guards it (placed AFTER the handler's load
+ * step to preserve cross-edition error precedence: unknown id + bad level
+ * = NOT_FOUND on both editions).
+ *
+ * Deliberate divergences from Cloud, ported as-is: no platform-anchor
+ * check (OSS has no IdentityProvider domain) and skill push is not wired
+ * (Cloud's push handler does not validate either) — do not "fix" these.
+ */
+import type { DescMessage } from "@bufbuild/protobuf";
+
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { UpdateVisibilityInputSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import {
+  supportedVisibilityLevels,
+  supportsVisibility,
+} from "../apiresource-meta.js";
+import {
+  failedPreconditionError,
+  internalError,
+  invalidArgumentError,
+} from "../errors.js";
+import { apiResourceKindName } from "../../store/proto-fields.js";
+import type { PipelineStep } from "../pipeline.js";
+import type { RequestContext } from "../request-context.js";
+import { metadataOf } from "./shapes.js";
+
+export function newValidateVisibilityStep<Desc extends DescMessage>(): PipelineStep<Desc> {
+  return {
+    name: "ValidateVisibility",
+    execute(ctx: RequestContext<Desc>): void {
+      const metadata = metadataOf(ctx.input);
+      if (metadata === undefined) {
+        return; // no metadata to validate — other steps own that failure
+      }
+      rejectUnsupportedVisibility(ctx.apiResourceKind, metadata.visibility);
+    },
+  };
+}
+
+export function newValidateVisibilityUpdateStep(): PipelineStep<
+  typeof UpdateVisibilityInputSchema
+> {
+  return {
+    name: "ValidateVisibilityUpdate",
+    execute(ctx: RequestContext<typeof UpdateVisibilityInputSchema>): void {
+      rejectUnsupportedVisibility(ctx.apiResourceKind, ctx.input.visibility);
+    },
+  };
+}
+
+/**
+ * Go RejectDefaultInstanceVisibilityUpdate: the canonical
+ * FAILED_PRECONDITION for a visibility update aimed at a system-managed
+ * default instance — the copy is cloud-identical and conformance-pinned;
+ * the PREDICATE lives in the instance controllers' own guard steps.
+ */
+export function rejectDefaultInstanceVisibilityUpdate(): never {
+  throw failedPreconditionError(
+    "Default instances do not have their own visibility - access always follows " +
+      "the parent blueprint. Change the blueprint's visibility instead.",
+  );
+}
+
+/** Go rejectUnsupportedVisibility (the shared level check + copy). */
+function rejectUnsupportedVisibility(
+  kind: ApiResourceKind,
+  visibility: ApiResourceVisibility,
+): void {
+  let supported: boolean;
+  let levels: string;
+  try {
+    supported = supportsVisibility(kind, visibility);
+    levels = supportedVisibilityLevels(kind);
+  } catch (error) {
+    throw internalError(error, "failed to resolve visibility config from kind");
+  }
+  if (supported) {
+    return;
+  }
+  throw invalidArgumentError(
+    `${apiResourceKindName(kind)} resources cannot be set to ${ApiResourceVisibility[visibility]}. Supported visibility levels: ${levels}.`,
+  );
+}

package/src/pipeline/steps/validation.ts

@@ -0,0 +1,45 @@
+/**
+ * ValidateProto — ports steps/validation.go. Redundant on the RPC path
+ * (the protovalidate interceptor already validated at the boundary) but
+ * deliberately retained: it is the ONLY validation on the direct-call path
+ * unit tests use, and the shared validator makes the overlap free.
+ */
+import { Code, ConnectError } from "@connectrpc/connect";
+import type { DescMessage } from "@bufbuild/protobuf";
+import { createValidator } from "@bufbuild/protovalidate";
+import type { Validator } from "@bufbuild/protovalidate";
+
+import type { PipelineStep } from "../pipeline.js";
+import type { RequestContext } from "../request-context.js";
+
+// Process-wide shared validator (Go SharedValidator): constraints compile
+// once, not per request.
+let sharedValidator: Validator | undefined;
+
+export function validator(): Validator {
+  if (sharedValidator === undefined) {
+    sharedValidator = createValidator();
+  }
+  return sharedValidator;
+}
+
+export function newValidateProtoStep<Desc extends DescMessage>(): PipelineStep<Desc> {
+  return {
+    name: "ValidateProto",
+    execute(ctx: RequestContext<Desc>): void {
+      const result = validator().validate(ctx.schema, ctx.input);
+      if (result.kind === "valid") {
+        return;
+      }
+      if (result.kind === "invalid") {
+        throw new ConnectError(result.error.message, Code.InvalidArgument);
+      }
+      // A rule that fails to compile/evaluate is a server defect, not bad
+      // input (same mapping as the transport interceptor).
+      throw new ConnectError(
+        `validation could not run: ${result.error.message}`,
+        Code.Internal,
+      );
+    },
+  };
+}