@qlever-llc/trellis 0.10.18-rc.1 → 0.10.18

package/script/generated-sdk/trellis-core/client.d.ts

@@ -1,18 +1,9 @@
-import type { AsyncResult, BaseError, EventListenerContext, EventOpts, HandlerTrellis, MaybeAsync, PreparedTrellisEvent, ReceiveTransferGrant, ReceiveTransferHandle, RequestOpts, Result, RpcHandlerContext, SendTransferGrant, SendTransferHandle, TrellisConnection, UnexpectedError, ValidationError } from "@qlever-llc/trellis";
+import type { AsyncResult, BaseError, HandlerTrellis, MaybeAsync, ReceiveTransferGrant, ReceiveTransferHandle, RequestOpts, RpcHandlerContext, SendTransferGrant, SendTransferHandle, TrellisConnection } from "@qlever-llc/trellis";
 import type { Api } from "./api.js";
 import type * as Types from "./types.js";
-import type * as HealthSdk from "@qlever-llc/trellis/sdk/health";
 type WithDeps<TDeps> = [TDeps] extends [undefined] ? {} : {
     deps: TDeps;
 };
-type EventCallback<TMessage> = {
-    bivarianceHack(message: TMessage, context: EventListenerContext): MaybeAsync<void, BaseError>;
-}["bivarianceHack"];
-type ServiceEventHandler<TEvent, TDeps = undefined> = (args: {
-    event: TEvent;
-    context: EventListenerContext;
-    client: HandlerClient;
-} & WithDeps<TDeps>) => MaybeAsync<void, BaseError>;
 type RpcHandler<TInput, TOutput, TDeps = undefined> = (args: {
     input: TInput;
     context: RpcHandlerContext;
@@ -35,15 +26,7 @@ export interface TrellisCoreClient {
             surfaceStatus(input: Types.TrellisSurfaceStatusInput, opts?: RequestOpts): AsyncResult<Types.TrellisSurfaceStatusOutput, BaseError>;
         };
     };
-    readonly event: {
-        readonly health: {
-            heartbeat: {
-                publish(event: Omit<HealthSdk.HealthHeartbeatEvent, "header">): AsyncResult<void, ValidationError | UnexpectedError>;
-                prepare(event: Omit<HealthSdk.HealthHeartbeatEvent, "header">): Result<PreparedTrellisEvent<Omit<HealthSdk.HealthHeartbeatEvent, "header">>, ValidationError | UnexpectedError>;
-                listen(handler: EventCallback<HealthSdk.HealthHeartbeatEvent>, subjectData?: Record<string, unknown>, opts?: EventOpts): AsyncResult<void, ValidationError | UnexpectedError>;
-            };
-        };
-    };
+    readonly event: {};
     readonly feed: {};
     readonly operation: {};
     wait(): AsyncResult<void, BaseError>;
@@ -57,15 +40,7 @@ export type ServiceWithDeps<TDeps> = Omit<TrellisCoreClient, "event"> & {
     readonly handle: ServiceHandle<TDeps>;
     with<TNextDeps>(deps: TNextDeps): ServiceWithDeps<TNextDeps>;
 };
-export interface ServiceEventSurface<TDeps> {
-    readonly health: {
-        heartbeat: {
-            publish(event: Omit<HealthSdk.HealthHeartbeatEvent, "header">): AsyncResult<void, ValidationError | UnexpectedError>;
-            prepare(event: Omit<HealthSdk.HealthHeartbeatEvent, "header">): Result<PreparedTrellisEvent<Omit<HealthSdk.HealthHeartbeatEvent, "header">>, ValidationError | UnexpectedError>;
-            listen(handler: ServiceEventHandler<HealthSdk.HealthHeartbeatEvent, TDeps>, subjectData?: Record<string, unknown>, opts?: EventOpts): AsyncResult<void, ValidationError | UnexpectedError>;
-        };
-    };
-}
+export type ServiceEventSurface<TDeps> = {};
 export interface ServiceHandle<TDeps = undefined> {
     readonly rpc: {
         readonly trellis: {

package/script/generated-sdk/trellis-core/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../../src/sdk/_generated/core/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../../src/sdk/_generated/core/client.ts"],"names":[],"mappings":"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"}

package/src/auth/browser/portal.ts

@@ -71,5 +71,6 @@ export function portalRedirectLocation(
 ): string | null {
   if (state?.status === "redirect") return state.location;
   if (state?.status === "approval_denied") return state.returnLocation ?? null;
+  if (state?.status === "expired") return state.returnLocation ?? null;
   return null;
 }

package/src/auth/browser.ts

@@ -45,6 +45,14 @@ export {
   signBytes,
 } from "./browser/session.js";
 export { deleteKeyPair, hasKeyPair } from "./browser/storage.js";
+export {
+  classifyBrowserAuthError,
+  isRecoverableBrowserAuthError,
+} from "./browser_recovery.js";
+export type {
+  BrowserAuthRecoveryClassification,
+  BrowserAuthRecoveryKind,
+} from "./browser_recovery.js";
 export {
   approvalCapabilityKeys,
   type ApprovalDecision as ApprovalDecisionData,

package/src/auth/browser_recovery.ts

@@ -0,0 +1,319 @@
+/** Browser auth recovery classification helpers. */
+
+/** Stable browser-auth recovery categories for app-owned recovery flows. */
+export type BrowserAuthRecoveryKind =
+  | "recoverable_stale_session"
+  | "recoverable_expired_flow"
+  | "recoverable_auth_required"
+  | "policy_denied"
+  | "insufficient_capabilities"
+  | "runtime_unavailable"
+  | "unknown";
+
+/** Classification result for a browser-auth related failure. */
+export type BrowserAuthRecoveryClassification = {
+  kind: BrowserAuthRecoveryKind;
+  recoverable: boolean;
+  reason?: string;
+  code?: string;
+};
+
+type ErrorSignal = {
+  code?: string;
+  reason?: string;
+  message?: string;
+};
+
+const MAX_ERROR_DEPTH = 8;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object";
+}
+
+function stringProperty(
+  record: Record<string, unknown>,
+  property: string,
+): string | undefined {
+  const value = record[property];
+  return typeof value === "string" ? value : undefined;
+}
+
+function normalize(value: string): string {
+  return value.trim().toLowerCase().replaceAll("-", "_").replaceAll(" ", "_");
+}
+
+function signalValue(signal: ErrorSignal): string | undefined {
+  return signal.code ?? signal.reason ?? signal.message;
+}
+
+function classification(
+  kind: BrowserAuthRecoveryKind,
+  recoverable: boolean,
+  signal?: ErrorSignal,
+): BrowserAuthRecoveryClassification {
+  const reason = signal?.reason ?? signalValue(signal ?? {});
+  return {
+    kind,
+    recoverable,
+    ...(reason ? { reason } : {}),
+    ...(signal?.code ? { code: signal.code } : {}),
+  };
+}
+
+function maybeSerializable(value: unknown): unknown {
+  if (!isRecord(value)) return undefined;
+  const toSerializable = value.toSerializable;
+  if (typeof toSerializable !== "function") return undefined;
+  try {
+    return toSerializable.call(value);
+  } catch {
+    return undefined;
+  }
+}
+
+function pushRecordSignals(
+  record: Record<string, unknown>,
+  signals: ErrorSignal[],
+  queue: unknown[],
+): void {
+  const message = stringProperty(record, "message");
+  const code = stringProperty(record, "code") ??
+    stringProperty(record, "error");
+  const reason = stringProperty(record, "reason") ??
+    stringProperty(record, "status");
+  if (message || code || reason) {
+    signals.push({
+      ...(code ? { code } : {}),
+      ...(reason ? { reason } : {}),
+      ...(message ? { message } : {}),
+    });
+  }
+
+  const context = record.context;
+  if (isRecord(context)) {
+    const contextReason = stringProperty(context, "reason");
+    const causeMessage = stringProperty(context, "causeMessage");
+    const contextCode = stringProperty(context, "code");
+    const contextMessage = stringProperty(context, "message");
+    if (contextReason || causeMessage || contextCode || contextMessage) {
+      signals.push({
+        ...(contextCode ? { code: contextCode } : {}),
+        ...(contextReason ? { reason: contextReason } : {}),
+        ...(causeMessage ?? contextMessage
+          ? { message: causeMessage ?? contextMessage }
+          : {}),
+      });
+    }
+    for (const nested of [context.cause, context.error, context.remoteError]) {
+      if (nested !== undefined) queue.push(nested);
+    }
+  }
+
+  for (const nested of [record.cause, record.error, record.remoteError]) {
+    if (nested !== undefined) queue.push(nested);
+  }
+}
+
+function collectErrorSignals(error: unknown): ErrorSignal[] {
+  const signals: ErrorSignal[] = [];
+  const queue: unknown[] = [error];
+  const seen = new WeakSet<object>();
+  let depth = 0;
+
+  while (queue.length > 0 && depth < MAX_ERROR_DEPTH) {
+    depth += 1;
+    const value = queue.shift();
+    if (typeof value === "string") {
+      signals.push({ message: value });
+      continue;
+    }
+    if (!isRecord(value)) continue;
+    if (seen.has(value)) continue;
+    seen.add(value);
+
+    if (value instanceof Error) {
+      signals.push({ message: value.message });
+    }
+    pushRecordSignals(value, signals, queue);
+
+    const serialized = maybeSerializable(value);
+    if (serialized && serialized !== value) queue.push(serialized);
+  }
+
+  return signals;
+}
+
+function hasNormalizedValue(
+  signals: ErrorSignal[],
+  values: ReadonlySet<string>,
+): ErrorSignal | undefined {
+  for (const signal of signals) {
+    for (const value of [signal.code, signal.reason]) {
+      if (value && values.has(normalize(value))) return signal;
+    }
+  }
+  return undefined;
+}
+
+function hasMessagePattern(
+  signals: ErrorSignal[],
+  patterns: readonly RegExp[],
+): ErrorSignal | undefined {
+  for (const signal of signals) {
+    const message = signal.message;
+    if (!message) continue;
+    const normalized = message.toLowerCase();
+    if (patterns.some((pattern) => pattern.test(normalized))) return signal;
+  }
+  return undefined;
+}
+
+function insufficientPermissionsAuthSignal(
+  signals: ErrorSignal[],
+): ErrorSignal | undefined {
+  for (const signal of signals) {
+    const reason = signal.reason ? normalize(signal.reason) : undefined;
+    const code = signal.code ? normalize(signal.code) : undefined;
+    if (reason !== "insufficient_permissions") continue;
+    if (code === "trellis.bootstrap.auth_required") return signal;
+    const message = signal.message?.toLowerCase() ?? "";
+    if (
+      message.includes("auth required") ||
+      message.includes("requires sign-in") ||
+      message.includes("requires signin") ||
+      message.includes("stale") ||
+      message.includes("session")
+    ) {
+      return signal;
+    }
+  }
+  return undefined;
+}
+
+const APPROVAL_DENIED_VALUES = new Set([
+  "approval_denied",
+  "trellis.auth.approval_denied",
+]);
+
+const INSUFFICIENT_CAPABILITIES_VALUES = new Set([
+  "insufficient_capabilities",
+  "trellis.auth.insufficient_capabilities",
+]);
+
+const RUNTIME_UNAVAILABLE_VALUES = new Set([
+  "trellis.bootstrap.not_ready",
+  "trellis.runtime.unavailable",
+  "runtime_unavailable",
+]);
+
+const EXPIRED_FLOW_VALUES = new Set([
+  "flow_expired",
+  "expired",
+  "trellis.auth.bind_expired",
+  "trellis.auth.flow_expired",
+]);
+
+const STALE_SESSION_VALUES = new Set([
+  "session_not_found",
+  "session_expired",
+  "user_not_found",
+  "contract_not_active",
+  "trellis.auth.session_not_found",
+  "trellis.auth.session_expired",
+  "trellis.auth.user_not_found",
+  "trellis.auth.contract_not_active",
+]);
+
+const AUTH_REQUIRED_VALUES = new Set([
+  "auth_required",
+  "trellis.bootstrap.auth_required",
+  "trellis.auth.login_failed",
+]);
+
+/**
+ * Classifies browser auth, bootstrap, callback, and transport-like failures.
+ *
+ * The classifier accepts raw errors, serialized Trellis errors, nested causes,
+ * and nested remote errors. Recoverable classifications are intended for
+ * app-owned flows that can clear stale auth and restart sign-in without showing a
+ * user-facing terminal error.
+ */
+export function classifyBrowserAuthError(
+  error: unknown,
+): BrowserAuthRecoveryClassification {
+  const signals = collectErrorSignals(error);
+
+  const approvalDenied = hasNormalizedValue(signals, APPROVAL_DENIED_VALUES) ??
+    hasMessagePattern(signals, [/approval .*denied/, /access .*denied/]);
+  if (approvalDenied) {
+    return classification("policy_denied", false, approvalDenied);
+  }
+
+  const inactiveOrInvalid = hasNormalizedValue(
+    signals,
+    new Set(["invalid_credentials", "user_inactive", "inactive_account"]),
+  ) ?? hasMessagePattern(signals, [
+    /invalid credential/,
+    /inactive account/,
+    /user inactive/,
+  ]);
+  if (inactiveOrInvalid) {
+    return classification("policy_denied", false, inactiveOrInvalid);
+  }
+
+  const insufficientCapabilities = hasNormalizedValue(
+    signals,
+    INSUFFICIENT_CAPABILITIES_VALUES,
+  ) ?? hasMessagePattern(signals, [/insufficient capabilit/]);
+  if (insufficientCapabilities) {
+    return classification(
+      "insufficient_capabilities",
+      false,
+      insufficientCapabilities,
+    );
+  }
+
+  const runtimeUnavailable = hasNormalizedValue(
+    signals,
+    RUNTIME_UNAVAILABLE_VALUES,
+  ) ?? hasMessagePattern(signals, [/runtime unavailable/]);
+  if (runtimeUnavailable) {
+    return classification("runtime_unavailable", false, runtimeUnavailable);
+  }
+
+  const expiredFlow = hasNormalizedValue(signals, EXPIRED_FLOW_VALUES) ??
+    hasMessagePattern(signals, [/flow .*expired/, /sign\-in .*expired/]);
+  if (expiredFlow) {
+    return classification("recoverable_expired_flow", true, expiredFlow);
+  }
+
+  const staleSession = hasNormalizedValue(signals, STALE_SESSION_VALUES) ??
+    hasMessagePattern(signals, [
+      /session .*expired/,
+      /session .*not found/,
+      /user .*not found/,
+      /contract .*not active/,
+    ]);
+  if (staleSession) {
+    return classification("recoverable_stale_session", true, staleSession);
+  }
+
+  const authRequired = hasNormalizedValue(signals, AUTH_REQUIRED_VALUES) ??
+    insufficientPermissionsAuthSignal(signals) ??
+    hasMessagePattern(signals, [
+      /auth required/,
+      /requires sign\-in/,
+      /requires signin/,
+      /requires authentication/,
+    ]);
+  if (authRequired) {
+    return classification("recoverable_auth_required", true, authRequired);
+  }
+
+  return classification("unknown", false);
+}
+
+/** Returns whether a browser auth error can silently restart sign-in. */
+export function isRecoverableBrowserAuthError(error: unknown): boolean {
+  return classifyBrowserAuthError(error).recoverable;
+}

package/src/auth/mod.ts

@@ -43,7 +43,10 @@ export {
 export {
   type AuthConfig,
   bindFlow,
+  type BrowserAuthRecoveryClassification,
+  type BrowserAuthRecoveryKind,
   buildLoginUrl,
+  classifyBrowserAuthError,
   clearSessionKey,
   createRpcProof,
   fetchPortalFlowState,
@@ -52,6 +55,7 @@ export {
   getPublicSessionKey,
   hasSessionKey,
   isBindSuccessResponse,
+  isRecoverableBrowserAuthError,
   loadSessionKey,
   natsConnectSigForIat,
   portalFlowIdFromUrl,

package/src/auth/protocol.ts

@@ -1215,6 +1215,7 @@ export const PortalFlowStateSchema = Type.Union([
   }),
   Type.Object({
     status: Type.Literal("expired"),
+    returnLocation: Type.Optional(Type.String({ minLength: 1 })),
   }),
 ]);
 export type PortalFlowState = StaticDecode<typeof PortalFlowStateSchema>;

package/src/browser.ts

@@ -6,6 +6,7 @@ import "./_dnt.polyfills.js";
 
 export {
   bindFlow,
+  classifyBrowserAuthError,
   clearSessionKey,
   createAuth,
   createRpcProof,
@@ -14,12 +15,15 @@ export {
   getPublicSessionKey,
   hasSessionKey,
   isBindSuccessResponse,
+  isRecoverableBrowserAuthError,
   loadSessionKey,
   signBytes,
 } from "./auth.js";
 export type {
   BindResponse,
   BindSuccessResponse,
+  BrowserAuthRecoveryClassification,
+  BrowserAuthRecoveryKind,
   NatsConnectOptions,
   SessionKeyHandle,
 } from "./auth.js";

package/src/client_connect.ts

@@ -1353,7 +1353,7 @@ async function resolveAuthRequired<
 
   if (isBrowserRuntime()) {
     globalThis.location.href = loginUrl;
-    throw new Error("Redirecting to Trellis login");
+    throw new ClientAuthHandledError();
   }
 
   throw new Error(

package/src/sdk/_generated/auth/api.ts

@@ -1,15 +1,12 @@
 // Generated from ./generated/contracts/manifests/trellis.auth@v1.json
 import { OWNED_API } from "./owned_api.js";
-import { OWNED_API as HealthApi } from "../health/mod.js";
 
 export { OWNED_API };
 
 export type UsedApi = {
   rpc: {};
   operations: {};
-  events: {
-    readonly "Health.Heartbeat": typeof HealthApi.events["Health.Heartbeat"];
-  };
+  events: {};
   feeds: {};
   subjects: {};
 };
@@ -17,11 +14,7 @@ export type UsedApi = {
 export const USED_API: UsedApi = {
   rpc: {},
   operations: {},
-  events: {
-    get "Health.Heartbeat"() {
-      return HealthApi.events["Health.Heartbeat"];
-    },
-  },
+  events: {},
   feeds: {},
   subjects: {},
 };

package/src/sdk/_generated/auth/client.ts

@@ -33,7 +33,6 @@ import type {
 } from "../../../index.js";
 import type { API, Api } from "./api.js";
 import type * as Types from "./types.js";
-import type * as HealthSdk from "../health/mod.js";
 
 type WithDeps<TDeps> = [TDeps] extends [undefined] ? {} : { deps: TDeps };
 
@@ -566,24 +565,6 @@ export interface TrellisAuthClient {
         ): AsyncResult<void, ValidationError | UnexpectedError>;
       };
     };
-    readonly health: {
-      heartbeat: {
-        publish(
-          event: Omit<HealthSdk.HealthHeartbeatEvent, "header">,
-        ): AsyncResult<void, ValidationError | UnexpectedError>;
-        prepare(
-          event: Omit<HealthSdk.HealthHeartbeatEvent, "header">,
-        ): Result<
-          PreparedTrellisEvent<Omit<HealthSdk.HealthHeartbeatEvent, "header">>,
-          ValidationError | UnexpectedError
-        >;
-        listen(
-          handler: EventCallback<HealthSdk.HealthHeartbeatEvent>,
-          subjectData?: Record<string, unknown>,
-          opts?: EventOpts,
-        ): AsyncResult<void, ValidationError | UnexpectedError>;
-      };
-    };
   };
   readonly feed: {};
   readonly operation: {
@@ -762,24 +743,6 @@ export interface ServiceEventSurface<TDeps> {
       ): AsyncResult<void, ValidationError | UnexpectedError>;
     };
   };
-  readonly health: {
-    heartbeat: {
-      publish(
-        event: Omit<HealthSdk.HealthHeartbeatEvent, "header">,
-      ): AsyncResult<void, ValidationError | UnexpectedError>;
-      prepare(
-        event: Omit<HealthSdk.HealthHeartbeatEvent, "header">,
-      ): Result<
-        PreparedTrellisEvent<Omit<HealthSdk.HealthHeartbeatEvent, "header">>,
-        ValidationError | UnexpectedError
-      >;
-      listen(
-        handler: ServiceEventHandler<HealthSdk.HealthHeartbeatEvent, TDeps>,
-        subjectData?: Record<string, unknown>,
-        opts?: EventOpts,
-      ): AsyncResult<void, ValidationError | UnexpectedError>;
-    };
-  };
 }
 
 export interface ServiceHandle<TDeps = undefined> {

package/src/sdk/_generated/auth/contract.ts

@@ -9575,7 +9575,10 @@ export const CONTRACT = {
         "required": ["status", "location"],
         "type": "object",
       }, {
-        "properties": { "status": { "const": "expired", "type": "string" } },
+        "properties": {
+          "returnLocation": { "minLength": 1, "type": "string" },
+          "status": { "const": "expired", "type": "string" },
+        },
         "required": ["status"],
         "type": "object",
       }],

package/src/sdk/_generated/core/api.ts

@@ -1,15 +1,12 @@
 // Generated from ./generated/contracts/manifests/trellis.core@v1.json
 import { OWNED_API } from "./owned_api.js";
-import { OWNED_API as HealthApi } from "../health/mod.js";
 
 export { OWNED_API };
 
 export type UsedApi = {
   rpc: {};
   operations: {};
-  events: {
-    readonly "Health.Heartbeat": typeof HealthApi.events["Health.Heartbeat"];
-  };
+  events: {};
   feeds: {};
   subjects: {};
 };
@@ -17,11 +14,7 @@ export type UsedApi = {
 export const USED_API: UsedApi = {
   rpc: {},
   operations: {},
-  events: {
-    get "Health.Heartbeat"() {
-      return HealthApi.events["Health.Heartbeat"];
-    },
-  },
+  events: {},
   feeds: {},
   subjects: {},
 };

package/src/sdk/_generated/core/client.ts

@@ -33,7 +33,6 @@ import type {
 } from "../../../index.js";
 import type { API, Api } from "./api.js";
 import type * as Types from "./types.js";
-import type * as HealthSdk from "../health/mod.js";
 
 type WithDeps<TDeps> = [TDeps] extends [undefined] ? {} : { deps: TDeps };
 
@@ -111,26 +110,7 @@ export interface TrellisCoreClient {
       ): AsyncResult<Types.TrellisSurfaceStatusOutput, BaseError>;
     };
   };
-  readonly event: {
-    readonly health: {
-      heartbeat: {
-        publish(
-          event: Omit<HealthSdk.HealthHeartbeatEvent, "header">,
-        ): AsyncResult<void, ValidationError | UnexpectedError>;
-        prepare(
-          event: Omit<HealthSdk.HealthHeartbeatEvent, "header">,
-        ): Result<
-          PreparedTrellisEvent<Omit<HealthSdk.HealthHeartbeatEvent, "header">>,
-          ValidationError | UnexpectedError
-        >;
-        listen(
-          handler: EventCallback<HealthSdk.HealthHeartbeatEvent>,
-          subjectData?: Record<string, unknown>,
-          opts?: EventOpts,
-        ): AsyncResult<void, ValidationError | UnexpectedError>;
-      };
-    };
-  };
+  readonly event: {};
   readonly feed: {};
   readonly operation: {};
   wait(): AsyncResult<void, BaseError>;
@@ -147,26 +127,7 @@ export type ServiceWithDeps<TDeps> = Omit<TrellisCoreClient, "event"> & {
   with<TNextDeps>(deps: TNextDeps): ServiceWithDeps<TNextDeps>;
 };
 
-export interface ServiceEventSurface<TDeps> {
-  readonly health: {
-    heartbeat: {
-      publish(
-        event: Omit<HealthSdk.HealthHeartbeatEvent, "header">,
-      ): AsyncResult<void, ValidationError | UnexpectedError>;
-      prepare(
-        event: Omit<HealthSdk.HealthHeartbeatEvent, "header">,
-      ): Result<
-        PreparedTrellisEvent<Omit<HealthSdk.HealthHeartbeatEvent, "header">>,
-        ValidationError | UnexpectedError
-      >;
-      listen(
-        handler: ServiceEventHandler<HealthSdk.HealthHeartbeatEvent, TDeps>,
-        subjectData?: Record<string, unknown>,
-        opts?: EventOpts,
-      ): AsyncResult<void, ValidationError | UnexpectedError>;
-    };
-  };
-}
+export type ServiceEventSurface<TDeps> = {};
 
 export interface ServiceHandle<TDeps = undefined> {
   readonly rpc: {