Tighten HTTP error schemas, keep rich causes internally (#137)

* Tighten HTTP error schemas, keep rich causes internally

Establish a clear rule: Schema.TaggedError is HTTP wire-facing — every
field must be a safe public field. Data.TaggedError is internal-only;
it can carry rich cause: unknown for logging/debugging and can't be
accidentally wired to an HttpApi endpoint because it isn't a Schema.

- OpenApiParseError (HTTP-exposed): drop error: Schema.Defect field
- GraphqlIntrospectionError (HTTP-exposed): drop error: Schema.Defect
  field; log underlying causes via Effect.logError at construction
  sites in introspect.ts
- OpenApiInvocationError, GraphqlInvocationError, GoogleDiscoveryParseError,
  GoogleDiscoveryInvocationError, KeychainError, ToolInvocationError:
  convert Schema.TaggedError -> Data.TaggedError, rename error -> cause
- Cloud auth (UserStoreError, WorkOSError): keep empty schema + 500
  annotation, log full cause via Effect.tapErrorCause at service wrappers

* Extract withServiceLogging helper + errors.test.ts contract

Collapse the repetitive tapErrorCause + mapError + withSpan ceremony
at each service wrapper into one helper in auth/errors.ts. Add a real
HttpApi integration test that pins down the contract:

  - Wire response contains only declared tagged-error fields
  - Server-side logs capture the full Cause chain (drizzle query,
    params, nested pg Error.cause)

The test uses a real HttpApi + HttpApiBuilder.toWebHandler + fetch
round-trip with a capturing Logger to verify both sides without
mocking. Validates Option C from the earlier discussion: service-level
logging is the only pattern that preserves the full cause because
mapError discards it before any edge middleware could see it.

* Remove errors.test.ts

* Simplify graphql introspection error handling

Drop ad-hoc Effect.logError sprinkles on branch-level failures (bad
status, returned errors, missing __schema) — the tagged error's message
already carries the useful info and there's no Cause chain to tap. Keep
tapErrorCause + mapError inline for the two cases where an upstream
error exists (HTTP request failure, JSON parse failure).

Author: RhysSullivan

apps/cloud/src/auth/context.ts

@@ -1,7 +1,7 @@
 import { Context, Effect, Layer } from "effect";
 import { makeUserStore } from "../services/user-store";
 import { DbService } from "../services/db";
-import { UserStoreError } from "./errors";
+import { UserStoreError, withServiceLogging } from "./errors";
 
 // AuthContext is defined in ./middleware.ts to keep middleware-related types together.
 export { AuthContext } from "./middleware";
@@ -12,24 +12,14 @@ export { AuthContext } from "./middleware";
 
 type RawStore = ReturnType<typeof makeUserStore>;
 
-const makeService = (store: RawStore) => {
-  const use = <A>(fn: (s: RawStore) => Promise<A>) =>
-    Effect.tryPromise({
-      try: () => fn(store),
-      catch: (cause) => cause,
-    }).pipe(
-      Effect.tapError((cause) =>
-        Effect.sync(() => {
-          // eslint-disable-next-line no-console
-          console.error("[user_store] query failed:", cause);
-        }),
-      ),
-      Effect.mapError(() => new UserStoreError()),
-      Effect.withSpan("user_store"),
-    );
-
-  return { use };
-};
+const makeService = (store: RawStore) => ({
+  use: <A>(fn: (s: RawStore) => Promise<A>) =>
+    withServiceLogging(
+      "user_store",
+      () => new UserStoreError(),
+      Effect.tryPromise({ try: () => fn(store), catch: (e) => e }),
+    ),
+});
 
 type UserStoreServiceType = ReturnType<typeof makeService>;
 

apps/cloud/src/auth/errors.ts

@@ -1,10 +1,6 @@
 import { HttpApiSchema } from "@effect/platform";
-import { Schema } from "effect";
+import { Effect, Schema } from "effect";
 
-// Tagged errors returned to HTTP clients. The response payload must NEVER
-// include internal details (SQL, stack traces, WorkOS error bodies) — those
-// can leak schema + secrets. Keep the schema empty and log the `cause`
-// server-side via Effect's logger when the error is constructed.
 export class UserStoreError extends Schema.TaggedError<UserStoreError>()(
   "UserStoreError",
   {},
@@ -16,3 +12,26 @@ export class WorkOSError extends Schema.TaggedError<WorkOSError>()(
   {},
   HttpApiSchema.annotations({ status: 500 }),
 ) {}
+
+/**
+ * Service-boundary error wrapper. Logs the full Cause chain (drizzle
+ * query/params, pg error codes, nested Error.cause, etc.) via Effect's
+ * structured logger, then maps to a tagged error so the HTTP wire
+ * response contains only safe fields.
+ *
+ * Use this whenever a Promise-based API gets lifted into an Effect and
+ * its failure needs both debuggable server-side logging and a safe
+ * public shape.
+ */
+export const withServiceLogging = <A, E, R>(
+  name: string,
+  publicError: () => E,
+  effect: Effect.Effect<A, unknown, R>,
+): Effect.Effect<A, E, R> =>
+  effect.pipe(
+    Effect.tapErrorCause((cause) =>
+      Effect.logError(`${name} failed`, cause),
+    ),
+    Effect.mapError(publicError),
+    Effect.withSpan(name),
+  );

apps/cloud/src/auth/workos.ts

@@ -4,7 +4,7 @@
 
 import { Context, Effect, Layer } from "effect";
 import { WorkOS } from "@workos-inc/node/worker";
-import { WorkOSError } from "./errors";
+import { WorkOSError, withServiceLogging } from "./errors";
 import { server } from "../env";
 
 const COOKIE_NAME = "wos-session";
@@ -26,18 +26,10 @@ const make = Effect.gen(function* () {
   const workos = new WorkOS({ apiKey, clientId });
 
   const use = <A>(fn: (wos: WorkOS) => Promise<A>) =>
-    Effect.tryPromise({
-      try: () => fn(workos),
-      catch: (cause) => cause,
-    }).pipe(
-      Effect.tapError((cause) =>
-        Effect.sync(() => {
-          // eslint-disable-next-line no-console
-          console.error("[workos] call failed:", cause);
-        }),
-      ),
-      Effect.mapError(() => new WorkOSError()),
-      Effect.withSpan("workos"),
+    withServiceLogging(
+      "workos",
+      () => new WorkOSError(),
+      Effect.tryPromise({ try: () => fn(workos), catch: (e) => e }),
     );
 
   const authenticateSealedSession = (sessionData: string) =>

packages/core/sdk/src/errors.ts

@@ -1,4 +1,4 @@
-import { Schema } from "effect";
+import { Data, Schema } from "effect";
 
 import { ToolId, SecretId, PolicyId } from "./ids";
 
@@ -7,14 +7,13 @@ export class ToolNotFoundError extends Schema.TaggedError<ToolNotFoundError>()(
   { toolId: ToolId },
 ) {}
 
-export class ToolInvocationError extends Schema.TaggedError<ToolInvocationError>()(
+export class ToolInvocationError extends Data.TaggedError(
   "ToolInvocationError",
-  {
-    toolId: ToolId,
-    message: Schema.String,
-    cause: Schema.optional(Schema.Unknown),
-  },
-) {}
+)<{
+  readonly toolId: ToolId;
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
 
 export class SecretNotFoundError extends Schema.TaggedError<SecretNotFoundError>()(
   "SecretNotFoundError",

packages/plugins/google-discovery/src/sdk/document.ts

@@ -140,8 +140,8 @@ const DiscoveryDocumentModel = Schema.Struct({
 });
 type DiscoveryDocument = typeof DiscoveryDocumentModel.Type;
 
-const toParseError = (message: string, error: unknown) =>
-  new GoogleDiscoveryParseError({ message, error });
+const toParseError = (message: string, cause: unknown) =>
+  new GoogleDiscoveryParseError({ message, cause });
 
 const decodeUnknownWith = <A>(
   message: string,
@@ -436,7 +436,6 @@ const manifestMethodFromMethod = (input: {
     if (!method.httpMethod) {
       return yield* new GoogleDiscoveryParseError({
         message: `Google Discovery method '${methodId}' is missing httpMethod`,
-        error: new Error(`Missing httpMethod for ${methodId}`),
       });
     }
 
@@ -509,7 +508,6 @@ export const extractGoogleDiscoveryManifest = Effect.fn(
     return yield* new GoogleDiscoveryParseError({
       message:
         "Google Discovery document is missing one of: name, version, rootUrl",
-      error: new Error("Invalid document"),
     });
   }
 

packages/plugins/google-discovery/src/sdk/errors.ts

@@ -1,21 +1,20 @@
-import { Schema } from "effect";
+import { Data, Schema } from "effect";
+import type { Option } from "effect";
 
-export class GoogleDiscoveryParseError extends Schema.TaggedError<GoogleDiscoveryParseError>()(
+export class GoogleDiscoveryParseError extends Data.TaggedError(
   "GoogleDiscoveryParseError",
-  {
-    message: Schema.String,
-    error: Schema.Defect,
-  },
-) {}
+)<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
 
-export class GoogleDiscoveryInvocationError extends Schema.TaggedError<GoogleDiscoveryInvocationError>()(
+export class GoogleDiscoveryInvocationError extends Data.TaggedError(
   "GoogleDiscoveryInvocationError",
-  {
-    message: Schema.String,
-    statusCode: Schema.optionalWith(Schema.Number, { as: "Option" }),
-    error: Schema.Defect,
-  },
-) {}
+)<{
+  readonly message: string;
+  readonly statusCode: Option.Option<number>;
+  readonly cause?: unknown;
+}> {}
 
 export class GoogleDiscoveryOAuthError extends Schema.TaggedError<GoogleDiscoveryOAuthError>()(
   "GoogleDiscoveryOAuthError",

packages/plugins/google-discovery/src/sdk/invoke.ts

@@ -277,7 +277,6 @@ const invoke = Effect.fn("GoogleDiscovery.invoke")(function* (input: {
         return yield* new GoogleDiscoveryInvocationError({
           message: `Missing required ${parameter.location} parameter: ${parameter.name}`,
           statusCode: Option.none(),
-          error: undefined,
         });
       }
       continue;
@@ -327,7 +326,7 @@ const invoke = Effect.fn("GoogleDiscovery.invoke")(function* (input: {
         new GoogleDiscoveryInvocationError({
           message: `HTTP request failed: ${err.message}`,
           statusCode: Option.none(),
-          error: err,
+          cause: err,
         }),
     ),
   );

packages/plugins/graphql/src/sdk/errors.ts

@@ -1,10 +1,10 @@
-import { Schema } from "effect";
+import { Data, Schema } from "effect";
+import type { Option } from "effect";
 
 export class GraphqlIntrospectionError extends Schema.TaggedError<GraphqlIntrospectionError>()(
   "GraphqlIntrospectionError",
   {
     message: Schema.String,
-    error: Schema.Defect,
   },
 ) {}
 
@@ -15,11 +15,10 @@ export class GraphqlExtractionError extends Schema.TaggedError<GraphqlExtraction
   },
 ) {}
 
-export class GraphqlInvocationError extends Schema.TaggedError<GraphqlInvocationError>()(
+export class GraphqlInvocationError extends Data.TaggedError(
   "GraphqlInvocationError",
-  {
-    message: Schema.String,
-    statusCode: Schema.optionalWith(Schema.Number, { as: "Option" }),
-    error: Schema.Defect,
-  },
-) {}
+)<{
+  readonly message: string;
+  readonly statusCode: Option.Option<number>;
+  readonly cause?: unknown;
+}> {}

packages/plugins/graphql/src/sdk/introspect.ts

@@ -149,29 +149,31 @@ export const introspect = Effect.fn("GraphQL.introspect")(function* (
   }
 
   const response = yield* client.execute(request).pipe(
+    Effect.tapErrorCause((cause) =>
+      Effect.logError("graphql introspection request failed", cause),
+    ),
     Effect.mapError(
       (err) =>
         new GraphqlIntrospectionError({
           message: `Failed to reach GraphQL endpoint: ${err.message}`,
-          error: err,
         }),
     ),
   );
 
   if (response.status !== 200) {
-    const body = yield* response.text.pipe(Effect.catchAll(() => Effect.succeed("")));
     return yield* new GraphqlIntrospectionError({
-      message: `Introspection failed with status ${response.status}: ${body}`,
-      error: undefined,
+      message: `Introspection failed with status ${response.status}`,
     });
   }
 
   const raw = yield* response.json.pipe(
+    Effect.tapErrorCause((cause) =>
+      Effect.logError("graphql introspection JSON parse failed", cause),
+    ),
     Effect.mapError(
-      (err) =>
+      () =>
         new GraphqlIntrospectionError({
           message: `Failed to parse introspection response as JSON`,
-          error: err,
         }),
     ),
   );
@@ -180,16 +182,13 @@ export const introspect = Effect.fn("GraphQL.introspect")(function* (
 
   if (json.errors && Array.isArray(json.errors) && json.errors.length > 0) {
     return yield* new GraphqlIntrospectionError({
-      // @effect-diagnostics-next-line preferSchemaOverJson:off
-      message: `Introspection returned errors: ${JSON.stringify(json.errors)}`,
-      error: undefined,
+      message: `Introspection returned ${json.errors.length} error(s)`,
     });
   }
 
   if (!json.data?.__schema) {
     return yield* new GraphqlIntrospectionError({
       message: "Introspection response missing __schema",
-      error: undefined,
     });
   }
 
@@ -216,6 +215,5 @@ export const parseIntrospectionJson = (
     catch: (err) =>
       new GraphqlIntrospectionError({
         message: `Failed to parse introspection JSON: ${err instanceof Error ? err.message : String(err)}`,
-        error: err,
       }),
   });

packages/plugins/graphql/src/sdk/invoke.ts

@@ -109,7 +109,7 @@ export const invoke = Effect.fn("GraphQL.invoke")(function* (
         new GraphqlInvocationError({
           message: `GraphQL request failed: ${err.message}`,
           statusCode: Option.none(),
-          error: err,
+          cause: err,
         }),
     ),
   );