cursedbelt 2.7.0 → 3.0.0

package/src/server/ws/hub.ts

@@ -1,168 +0,0 @@
-import type { Server, ServerWebSocket } from 'bun';
-import type { MiddlewareHandler } from 'hono';
-import { ApiError, toErrorEnvelope } from '../errors';
-import { computePresence } from './presence';
-import { joinRoom, ROOM_META_KEY } from './room';
-import type {
-  WsChannel,
-  WsClient,
-  WsData,
-  WsHandshake,
-  WsHub,
-  WsHubOpts,
-  WsMessage,
-} from './types';
-
-const DEFAULT_HEARTBEAT_MS = 30_000;
-const DEFAULT_STALE_MS = 120_000;
-/** Bun's `idleTimeout` ceiling (seconds). */
-const BUN_IDLE_TIMEOUT_MAX_S = 960;
-
-/** Serialize the wire envelope once per fan-out. */
-const encode = (event: string, data: unknown): string => JSON.stringify({ event, data });
-
-/**
- * The heartbeat sweep, factored out as a pure function so it's testable without faking
- * timers: ping every live client, close (don't delete — let the `close` handler fire
- * `onDisconnect` + remove) any unheard-from past `staleMs`. The hub's `setInterval`
- * calls this with `Date.now()`.
- */
-export function sweepStaleClients(clients: Iterable<WsClient>, now: number, staleMs: number): void {
-  for (const client of clients) {
-    if (now - client.lastPingAt > staleMs) {
-      client.ws.close(1001, 'stale');
-    } else {
-      client.ws.ping();
-    }
-  }
-}
-
-/**
- * Build a typed WebSocket hub on Bun's native upgrade. The hub owns the transport —
- * connection registry, channel routing, heartbeat/stale-cull, and presence-as-a-view;
- * the registered {@link WsChannel}s own the business logic. Mount {@link WsHub.upgradeHandler}
- * on the Hono upgrade route(s) and hand {@link WsHub.handlers} to `serveBun`'s `websocket`.
- *
- * @example
- * const hub = createWsHub({ channels: wsChannels, authenticate });
- * app.get('/ws/:channel', hub.upgradeHandler);
- * serveBun(app, { port, websocket: hub.handlers });
- */
-export function createWsHub<T extends Record<string, WsChannel<any>>>(opts: WsHubOpts<T>): WsHub {
-  const clients = new Map<string, WsClient>();
-  const staleMs = opts.staleMs ?? DEFAULT_STALE_MS;
-  const heartbeatMs = opts.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_MS;
-
-  const channelOf = (name: string): WsChannel<any> | undefined => opts.channels[name];
-  const clientFromWs = (ws: ServerWebSocket<WsData>): WsClient | undefined =>
-    clients.get(ws.data.clientId);
-
-  // Our heartbeat is authoritative (it also drives presence), so disable Bun's auto-ping
-  // and let its idle timeout backstop just beyond our stale window.
-  const idleTimeout = Math.min(Math.ceil(staleMs / 1000), BUN_IDLE_TIMEOUT_MAX_S);
-
-  const heartbeat = setInterval(() => {
-    sweepStaleClients(clients.values(), Date.now(), staleMs);
-  }, heartbeatMs);
-  // Don't keep the process alive for the heartbeat alone (server tests, graceful exit).
-  heartbeat.unref?.();
-
-  const upgradeHandler: MiddlewareHandler = async (c) => {
-    const channel = c.req.param('channel') ?? c.req.query('channel') ?? 'default';
-    const room = c.req.query('room') ?? undefined;
-    const handshake: WsHandshake = { headers: c.req.raw.headers, url: c.req.url, channel, room };
-
-    let user: Awaited<ReturnType<typeof opts.authenticate>>;
-    try {
-      user = await opts.authenticate(handshake);
-    } catch {
-      user = null;
-    }
-    if (!user) return c.json(toErrorEnvelope(new ApiError(401, 'Unauthorized')), 401);
-
-    const data: WsData = { clientId: crypto.randomUUID(), user, channel, room };
-    const server = c.env as unknown as Server<WsData>;
-    const upgraded = server.upgrade(c.req.raw, { data });
-    if (!upgraded) return c.text('Upgrade required', 426);
-    // Bun has taken over the socket and sent the 101; this Response is discarded by
-    // Bun.serve. (A real 101 can't be constructed — the Fetch Response ctor forbids 1xx.)
-    return c.body(null, 204);
-  };
-
-  const hub: WsHub = {
-    upgradeHandler,
-    handlers: {
-      idleTimeout,
-      sendPings: false,
-      open(ws) {
-        const { clientId, user, channel, room } = ws.data;
-        const now = Date.now();
-        const client: WsClient = {
-          id: clientId,
-          user,
-          ws,
-          channel,
-          connectedAt: now,
-          lastPingAt: now,
-          meta: {},
-        };
-        if (room) joinRoom(client, room);
-        clients.set(clientId, client);
-        channelOf(channel)?.onConnect?.(client, hub);
-      },
-      message(ws, raw) {
-        const client = clientFromWs(ws);
-        if (!client) return;
-        client.lastPingAt = Date.now();
-        let msg: WsMessage;
-        try {
-          msg = JSON.parse(typeof raw === 'string' ? raw : raw.toString());
-        } catch {
-          return; // ignore malformed frames rather than crash the socket
-        }
-        channelOf(client.channel)?.onMessage(client, msg, hub);
-      },
-      // A pong (reply to our heartbeat ping) proves liveness without an app message.
-      pong(ws) {
-        const client = clientFromWs(ws);
-        if (client) client.lastPingAt = Date.now();
-      },
-      close(ws) {
-        const client = clientFromWs(ws);
-        if (!client) return;
-        channelOf(client.channel)?.onDisconnect?.(client, hub);
-        clients.delete(client.id);
-      },
-    },
-    broadcast(channel, event, data) {
-      const payload = encode(event, data);
-      for (const client of clients.values()) {
-        if (client.channel === channel) client.ws.send(payload);
-      }
-    },
-    broadcastToRoom(channel, roomId, event, data) {
-      const payload = encode(event, data);
-      for (const client of clients.values()) {
-        if (client.channel === channel && client.meta[ROOM_META_KEY] === roomId) {
-          client.ws.send(payload);
-        }
-      }
-    },
-    send(clientId, event, data) {
-      clients.get(clientId)?.ws.send(encode(event, data));
-    },
-    getClients(channel) {
-      const all = [...clients.values()];
-      return channel ? all.filter((client) => client.channel === channel) : all;
-    },
-    getClient: (id) => clients.get(id),
-    getPresence(channel) {
-      return computePresence(clients.values(), channel, channelOf(channel)?.presence ?? false);
-    },
-    close() {
-      clearInterval(heartbeat);
-    },
-  };
-
-  return hub;
-}

package/src/server/ws/index.ts

@@ -1,20 +0,0 @@
-// cursedbelt/server WS hub — Bun-native upgrade, typed channel registry, heartbeat,
-// presence-as-a-view, and the push-only event-bus subset. Pairs with the partysocket
-// client in `cursedbelt/client`.
-export { createEventBus } from './eventBus';
-export { createWsHub } from './hub';
-export { computePresence } from './presence';
-export { joinRoom, leaveRoom, ROOM_META_KEY, roomOf } from './room';
-export type {
-  EventBus,
-  EventBusData,
-  PresenceEntry,
-  PresenceState,
-  WsChannel,
-  WsClient,
-  WsData,
-  WsHandshake,
-  WsHub,
-  WsHubOpts,
-  WsMessage,
-} from './types';

package/src/server/ws/presence.spec.ts

@@ -1,27 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import type { AuthUser } from '../auth/types';
-import { computePresence } from './presence';
-import type { WsClient } from './types';
-
-const user = (id: string): AuthUser => ({ id, roles: [], getOnly: false, sessionId: `s-${id}` });
-const client = (id: string, channel: string, connectedAt: number): WsClient =>
-  ({ id, user: user(id), channel, connectedAt, meta: {} }) as unknown as WsClient;
-
-describe('computePresence', () => {
-  test('returns one row per client on the channel when enabled', () => {
-    const clients = [client('a', 'chat', 100), client('b', 'chat', 200), client('c', 'game', 300)];
-    expect(computePresence(clients, 'chat', true)).toEqual([
-      { userId: 'a', connectedAt: 100 },
-      { userId: 'b', connectedAt: 200 },
-    ]);
-  });
-
-  test('returns empty when presence is not enabled for the channel', () => {
-    const clients = [client('a', 'chat', 100)];
-    expect(computePresence(clients, 'chat', false)).toEqual([]);
-  });
-
-  test('returns empty for a channel with no clients', () => {
-    expect(computePresence([], 'chat', true)).toEqual([]);
-  });
-});

package/src/server/ws/presence.ts

@@ -1,26 +0,0 @@
-import type { PresenceState, WsClient } from './types';
-
-/**
- * Presence is a *view* over the live client map, not a tracked structure — there is no
- * `PresenceTracker` class to keep in sync. The hub's `getPresence(channel)` delegates
- * here; a channel that wants to push presence does
- * `hub.broadcast('chat', 'presence', hub.getPresence('chat'))` from its lifecycle hooks.
- */
-
-/** The presence snapshot for `channel`: one `{ userId, connectedAt }` row per live
- * client on that channel, or empty when the channel doesn't opt into presence.
- * Pure (no timers, no state) so it's trivially testable. */
-export function computePresence(
-  clients: Iterable<WsClient>,
-  channel: string,
-  presenceEnabled: boolean,
-): PresenceState {
-  if (!presenceEnabled) return [];
-  const rows: PresenceState = [];
-  for (const client of clients) {
-    if (client.channel === channel) {
-      rows.push({ userId: client.user.id, connectedAt: client.connectedAt });
-    }
-  }
-  return rows;
-}

package/src/server/ws/room.spec.ts

@@ -1,36 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { joinRoom, leaveRoom, ROOM_META_KEY, roomOf } from './room';
-import type { WsClient } from './types';
-
-const client = (): WsClient => ({ id: 'c', meta: {} }) as unknown as WsClient;
-
-describe('room helpers', () => {
-  test('joinRoom sets the room meta under ROOM_META_KEY; roomOf reads it', () => {
-    const c = client();
-    expect(roomOf(c)).toBeUndefined();
-    joinRoom(c, 'lobby');
-    expect(c.meta[ROOM_META_KEY]).toBe('lobby');
-    expect(roomOf(c)).toBe('lobby');
-  });
-
-  test('joinRoom replaces the current room', () => {
-    const c = client();
-    joinRoom(c, 'a');
-    joinRoom(c, 'b');
-    expect(roomOf(c)).toBe('b');
-  });
-
-  test('leaveRoom clears membership', () => {
-    const c = client();
-    joinRoom(c, 'a');
-    leaveRoom(c);
-    expect(roomOf(c)).toBeUndefined();
-    expect(c.meta[ROOM_META_KEY]).toBeUndefined();
-  });
-
-  test('roomOf ignores a non-string meta value', () => {
-    const c = client();
-    c.meta[ROOM_META_KEY] = 42;
-    expect(roomOf(c)).toBeUndefined();
-  });
-});

package/src/server/ws/room.ts

@@ -1,29 +0,0 @@
-import type { WsClient } from './types';
-
-/**
- * Rooms are not a separate stateful abstraction — they are a typed convention over
- * {@link WsClient.meta}. A channel puts a client in a room with {@link joinRoom}; the
- * hub's `broadcastToRoom` matches on the same key. This replaces the old `wsRoom.ts` /
- * `reconnectableRoom.ts` classes: the hub owns connections + fan-out, the channel owns
- * membership + any history buffer.
- */
-
-/** The {@link WsClient.meta} key a client's current room id lives under. The hub's
- * `broadcastToRoom` reads the same key — keep them in lockstep. */
-export const ROOM_META_KEY = 'roomId';
-
-/** Put `client` in `roomId` (replaces any current room). */
-export function joinRoom(client: WsClient, roomId: string): void {
-  client.meta[ROOM_META_KEY] = roomId;
-}
-
-/** Remove `client` from its room (a subsequent room broadcast won't reach it). */
-export function leaveRoom(client: WsClient): void {
-  delete client.meta[ROOM_META_KEY];
-}
-
-/** The client's current room id, or undefined if it isn't in one. */
-export function roomOf(client: WsClient): string | undefined {
-  const room = client.meta[ROOM_META_KEY];
-  return typeof room === 'string' ? room : undefined;
-}

package/src/server/ws/types.ts

@@ -1,134 +0,0 @@
-import type { ServerWebSocket, WebSocketHandler } from 'bun';
-import type { MiddlewareHandler } from 'hono';
-import type { AuthUser } from '../auth/types';
-
-/**
- * Shared types for the cursedbelt WebSocket hub.
- *
- * cursedbelt owns the *transport* — connection lifecycle, channel routing,
- * heartbeat/stale-cull, presence-as-a-view, and an injected `authenticate`
- * callback. The *channels* (what each message means, the per-feature game/chat
- * state) stay app-business; an app registers its channels into the hub and
- * consumes the broadcast helpers. ru's push-only variant is {@link EventBus}.
- *
- * Built on Bun's native WS upgrade (`Server.upgrade` + `Bun.serve { websocket }`),
- * surfaced through Hono via {@link WsHub.upgradeHandler}. No `ws`-lib, no adapter.
- */
-
-/** The JSON envelope every frame uses, both directions: `{ event, data }`. The hub
- * emits this from {@link WsHub.broadcast}/`send`; channels receive the parsed inbound
- * envelope as their `onMessage` payload. `T` narrows `data` for a typed channel. */
-export interface WsMessage<T = unknown> {
-  event: string;
-  data: T;
-}
-
-/** What the hub stashes on the Bun `ServerWebSocket.data` at upgrade time so `open`
- * can register the client without a second handshake round-trip (see the gotcha in
- * the task spec). `room` is the optional `?room=` query param — a named room within
- * the channel, applied to {@link WsClient.meta} on connect. */
-export interface WsData {
-  clientId: string;
-  user: AuthUser;
-  channel: string;
-  room?: string;
-}
-
-/** The minimal view of the WS handshake handed to {@link WsHubOpts.authenticate}. The
- * app reads its auth cookie off `headers` and verifies it (cursedbelt never reads the
- * cookie itself — auth *model* is app business). */
-export interface WsHandshake {
-  headers: Headers;
-  url: string;
-  channel: string;
-  room?: string;
-}
-
-/** A live connection. `meta` is the per-channel scratch bag (room membership via the
- * `room.ts` helpers, game seat, typing flag, …) — the hub never interprets it beyond
- * {@link WsHub.broadcastToRoom}'s room match. `lastPingAt` is "last time we heard from
- * this client" (an inbound message OR a pong); the heartbeat culls on it. */
-export interface WsClient {
-  id: string;
-  user: AuthUser;
-  ws: ServerWebSocket<WsData>;
-  channel: string;
-  connectedAt: number;
-  lastPingAt: number;
-  meta: Record<string, unknown>;
-}
-
-/** A business channel registered into the hub. The hub routes inbound frames to
- * `onMessage` by {@link WsClient.channel} and fires the lifecycle hooks; everything
- * the handler *does* (broadcast shape, game state, history) is app business. */
-export interface WsChannel<TMsg = WsMessage> {
-  name: string;
-  /** Fired after the client is registered (room meta already applied). */
-  onConnect?(client: WsClient, hub: WsHub): void;
-  /** Fired once per inbound frame (the parsed `{ event, data }` envelope). */
-  onMessage(client: WsClient, msg: TMsg, hub: WsHub): void;
-  /** Fired when the socket closes (explicit, stale-culled, or peer-dropped). */
-  onDisconnect?(client: WsClient, hub: WsHub): void;
-  /** Whether this channel contributes to {@link WsHub.getPresence}. Default: false. */
-  presence?: boolean;
-}
-
-/** A presence row — the public, business-safe view of a connected client. */
-export interface PresenceEntry {
-  userId: string;
-  connectedAt: number;
-}
-
-/** The presence snapshot for a channel: one row per live, presence-enabled client. */
-export type PresenceState = PresenceEntry[];
-
-export interface WsHubOpts<TChannelMap extends Record<string, WsChannel<any>>> {
-  /** The business channel registry, keyed by channel name (the `?channel=`/`:channel`
-   * the client connects to). */
-  channels: TChannelMap;
-  /** Cookie→user verification for the handshake. Return `null` to reject the upgrade
-   * with a 401 (an HTTP 401, not a WS close). */
-  authenticate(handshake: WsHandshake): Promise<AuthUser | null>;
-  /** How often the heartbeat pings live clients + sweeps stale ones. Default 30_000. */
-  heartbeatIntervalMs?: number;
-  /** A client unheard-from for longer than this is culled. Default 120_000 (2 min). */
-  staleMs?: number;
-}
-
-export interface WsHub {
-  /** The Bun `websocket` config — pass straight to `serveBun(app, { websocket: hub.handlers })`.
-   * `message` is required by Bun; `open`/`close`/`pong` drive lifecycle + liveness. */
-  handlers: WebSocketHandler<WsData>;
-  /** Mount on the Hono upgrade route(s): `app.get('/ws/:channel', hub.upgradeHandler)`.
-   * Authenticates, then calls `Server.upgrade` (Bun-native). */
-  upgradeHandler: MiddlewareHandler;
-  /** Send `{ event, data }` to every client on `channel`. */
-  broadcast(channel: string, event: string, data: unknown): void;
-  /** Send `{ event, data }` to every client on `channel` whose room (meta) is `roomId`. */
-  broadcastToRoom(channel: string, roomId: string, event: string, data: unknown): void;
-  /** Send `{ event, data }` to one client by id (no-op if gone). */
-  send(clientId: string, event: string, data: unknown): void;
-  /** Live clients, optionally filtered to one channel. */
-  getClients(channel?: string): WsClient[];
-  /** One client by id, or undefined. */
-  getClient(clientId: string): WsClient | undefined;
-  /** The presence snapshot for a presence-enabled channel (empty otherwise). */
-  getPresence(channel: string): PresenceState;
-  /** Stop the heartbeat timer (call on shutdown / in tests to avoid a leaked interval). */
-  close(): void;
-}
-
-/** ru's push-only subset: broadcast-to-all, no auth, no inbound routing. One bus,
- * mounted once; ru's task queue / caSync / Forge workers call `broadcast`. */
-export interface EventBus {
-  /** Bun `websocket` config. `message` is a documented no-op (push-only). */
-  handlers: WebSocketHandler<EventBusData>;
-  upgradeHandler: MiddlewareHandler;
-  /** Push `{ event, data }` to every connected client. */
-  broadcast(event: string, data: unknown): void;
-  /** Number of connected clients. */
-  clientCount(): number;
-}
-
-/** The event bus carries no per-socket data (no auth, no channel). */
-export type EventBusData = Record<never, never>;

package/src/shared/errors.ts

@@ -1,153 +0,0 @@
-/**
- * The canonical server error class + error/validation envelope for the whole
- * monorepo — cursedbelt apps AND cursedshell plugins.
- *
- * Every API failure — thrown deep in a handler, surfaced by middleware, or raised
- * by a plugin service — is shaped into ONE wire contract, the **rich** envelope
- * defined once in cwip (`cwip/error`):
- *
- *   { "error": { "name", "message", "code?", "status?", "category?", "context?",
- *       "isOperational", "timestamp" }, "correlationId?": "…" }
- *
- * Clients parse exactly this shape, so there is no per-route error drift — and no
- * drift between a cwip-based server (which already emits it via `cwip/server`'s
- * `errorHandler`) and a cursedshell one. The extra fields are additive:
- * a client that only reads `message`/`code`/`context` keeps working unchanged.
- *
- * `ApiError` is the ergonomic throwable: `throw new ApiError(404, 'not found')`.
- * It is a thin subclass of cwip's `AppError` with the status-first constructor
- * shape every plugin already uses, so a single `getSummary()`/`toErrorEnvelope`
- * produces the rich body. The `errorEnvelope` Hono `onError` handler
- * (cursedbelt/server) turns it (and any other thrown value) into the envelope +
- * the right HTTP status; {@link ApiError.fromEnvelope} rebuilds one on the CLIENT
- * from a parsed error body.
- *
- * This module is **framework-free** (no Hono, no DOM, no server deps — it imports
- * only cwip's framework-free `cwip/error` and a type-only `zod` for the validation
- * builder), so it is safe to import from browser bundles and from cursedshell's
- * plugin-pure layer via the `cursedbelt/errors` subpath. Server code reaches the
- * same symbols through `cursedbelt/server` (which re-exports this module).
- */
-import {
-  AppError,
-  type AppErrorSummary,
-  type ErrorEnvelope,
-  isAppError,
-  type ToErrorEnvelopeOptions,
-  toErrorEnvelope,
-} from 'cwip/error';
-import type { ZodError } from 'zod';
-
-// ── Re-export the ONE canonical envelope + formatter (defined in cwip) ────────
-//    So `cursedbelt/errors` and `cwip/error` speak the exact same wire contract.
-export { AppError, type AppErrorSummary, type ErrorEnvelope, isAppError, type ToErrorEnvelopeOptions, toErrorEnvelope };
-
-// ── Throwable ────────────────────────────────────────────────────────────────
-
-export interface ApiErrorOptions {
-  /** Stable machine code carried into the envelope. */
-  code?: string;
-  /** Structured detail carried into the envelope (e.g. `{ issues }`). */
-  context?: Record<string, unknown>;
-  /** Underlying cause, preserved for server-side logging (never serialized). */
-  cause?: unknown;
-}
-
-/**
- * A throwable HTTP error carrying its status + canonical-envelope fields. A thin,
- * status-first subclass of cwip's {@link AppError} — `new ApiError(404, 'nope',
- * { code, context })` is the ergonomic form every handler/middleware/plugin
- * service uses; the inherited `getSummary()` yields the rich `AppErrorSummary` so
- * `toErrorEnvelope` maps it to the response with no extra work. On the client,
- * {@link ApiError.fromEnvelope} rebuilds it from a parsed error body so callers
- * can branch on `.status`/`.code`/`.context`.
- */
-export class ApiError extends AppError {
-  /**
-   * Always set — narrows the base's optional `status` (an `ApiError` is defined
-   * by its HTTP status). The value is assigned by `AppError`'s constructor from
-   * the `status` we pass through; `declare` just re-types it without re-emitting
-   * the field (so the base's assignment isn't shadowed under class-field semantics).
-   */
-  declare readonly status: number;
-
-  constructor(status: number, message: string, options: ApiErrorOptions = {}) {
-    super(message, {
-      status,
-      code: options.code,
-      context: options.context,
-      cause: options.cause,
-    });
-    // `AppError` sets `this.name = new.target.name` → 'ApiError' already.
-  }
-
-  /**
-   * Rebuild an `ApiError` from a parsed error envelope's `error` object — the
-   * client half of the contract (e.g. `createServiceClient`'s response parser).
-   * Reads only `message`/`code`/`context`, so it works against both the rich
-   * envelope and any legacy minimal body. Missing/absent envelope falls back to a
-   * status-derived message.
-   */
-  static fromEnvelope(status: number, envelope?: Partial<AppErrorSummary>): ApiError {
-    return new ApiError(status, envelope?.message ?? `Request failed with status ${status}`, {
-      code: envelope?.code,
-      context: envelope?.context,
-    });
-  }
-}
-
-/** Type guard for {@link ApiError} (the status-first server throwable). */
-export const isApiError = (value: unknown): value is ApiError => value instanceof ApiError;
-
-// ── Validation envelope (the ONE shape both zValidator and the cursedshell ────
-//    service-router emit; mirrors Zod's own `issue.path`) ─────────────────────
-
-/**
- * One field-level validation error on the wire. `path` is the dotted Zod path to
- * the offending field (`''` for a top-level/whole-body issue) — it mirrors
- * `z.ZodIssue.path`, so server code maps 1:1 and clients read a stable name.
- */
-export interface ValidationIssue {
-  /** Dotted path to the offending field (`''` for a top-level issue). */
-  path: string;
-  /** Human-readable, zod-authored message. */
-  message: string;
-}
-
-/**
- * The canonical machine code carried in a validation envelope's `error.code`, so a
- * client can branch on it without string-matching the (localizable) message.
- */
-export const VALIDATION_ERROR_CODE = 'validation';
-
-/** The HTTP status every validation failure maps to (both emitters respond 400). */
-export const VALIDATION_STATUS = 400;
-
-/** The default client-facing message when validation fails. */
-const DEFAULT_VALIDATION_MESSAGE = 'Validation failed';
-
-/** Map a {@link https://zod.dev | zod} error's issues to the wire {@link ValidationIssue}s. */
-export function toValidationIssues(error: ZodError): ValidationIssue[] {
-  return error.issues.map((issue) => ({
-    path: issue.path.map((segment) => String(segment)).join('.'),
-    message: issue.message,
-  }));
-}
-
-/**
- * Build the canonical validation envelope from a zod error (or pre-mapped issues).
- * It constructs an {@link ApiError} (status {@link VALIDATION_STATUS}, code
- * {@link VALIDATION_ERROR_CODE}, `context.issues`) and runs it through the shared
- * {@link toErrorEnvelope}, so a validation failure is shaped identically to every
- * other error on the wire — `{ error: { …, code: 'validation', status: 400,
- * context: { issues } } }`. This is the single builder — both cursedbelt's
- * `zValidator` middleware and cursedshell's `buildServiceRouter` call it, so a
- * client parses validation failures identically no matter which layer emitted them.
- */
-export function validationEnvelope(
-  errorOrIssues: ZodError | ValidationIssue[],
-  message: string = DEFAULT_VALIDATION_MESSAGE,
-): ErrorEnvelope {
-  const issues = Array.isArray(errorOrIssues) ? errorOrIssues : toValidationIssues(errorOrIssues);
-  return toErrorEnvelope(new ApiError(VALIDATION_STATUS, message, { code: VALIDATION_ERROR_CODE, context: { issues } }));
-}