ban Schema.Class, migrate all usage to Schema.Struct (#768)

Effect 4.x makes `Schema.Class` nominally typed at runtime — the encode
path does an `instanceof` check and rejects any plain object, regardless
of field shape. TypeScript's structural typing assigns plain objects to
Class-typed parameters happily, so the compiler can't catch the
mismatch. The result has bitten executor twice this week alone (Sentry
NODE-CLOUDFLARE-WORKERS-3N: Google user, Vercel user, and a fresh
SharePoint report today) — wire-decoded `oauth2` payloads reaching
`encodeSync` and crashing the txn with "Expected
OpenApiOAuth2SourceConfig, got {...}", surfacing to users as an opaque
`InternalError({ traceId })` after OAuth completes.

The Effect community has documented the same footgun for two years —
imagio and Patrick Roza in Feb 2024
(https://www.answeroverflow.com/m/1206705364288938064), and gcanti
himself in Nov 2025 confirming "TypeScript is structural" with the
explicit recommendation: "if you don't necessarily need the Schema.Class
features, then Schema.Struct is always a better option"
(https://www.answeroverflow.com/m/1268175268019830906). None of the
75-odd Class declarations in this repo had methods, getters, setters,
or any behavior beyond the schema — they were pure data shapes wearing
a class wrapper for no benefit.

This commit:

- Migrates every `Schema.Class<X>("X")(fields) {}` declaration to
  `Schema.Struct(fields)` + `type X = typeof X.Type` via
  `scripts/migrate-schema-class.ts`. The codemod is idempotent and
  supports `--dry-run`.
- Migrates `Schema.TaggedClass` (2 sites) to `Schema.TaggedStruct`.
- Rewrites ~460 `new X(...)` call sites to `X.make(...)`, the equivalent
  on Struct that applies constructor defaults and validates fields.
- `Schema.TaggedErrorClass` and `Schema.ErrorClass` are exempt — they're
  how Effect models typed-error channels and `instanceof` for them is
  by design.
- Consolidates the eight existing Struct/Class duality pairs
  (`OAuth2SourceConfig`/`Schema`, `OpenApiSourceBindingInput`/`Schema`,
  etc) — the Struct half was created to bridge the API boundary;
  with Class gone there's only one schema per shape.
- Replaces `instanceof FormElicitation` and `_tag === "..."` checks
  with hoisted `Schema.is(...)` predicates, satisfying the existing
  `no-manual-tag-check` and `no-inline-schema-compile` rules.
- Adds `executor/no-schema-class` oxlint rule banning `Schema.Class`
  and `Schema.TaggedClass` anywhere — `TaggedErrorClass`/`ErrorClass`
  pass through. Supersedes `no-schema-class-http-payload`, which only
  caught direct payload usage and missed nested-in-Struct cases (the
  exact shape the OAuth2 bug took).
- Deletes the now-redundant `check-http-payload-schemas.ts` script and
  its test — the new lint rule covers everything they did, more broadly.

Verified: full `bun run lint`, `bun run typecheck`, `bun run test`, and
`bun run format:check` clean.

Author: RhysSullivan

.oxlintrc.jsonc

@@ -23,7 +23,7 @@
     "executor/no-raw-fetch": "error",
     "executor/no-redundant-primitive-cast": "error",
     "executor/no-redundant-error-factory": "error",
-    "executor/no-schema-class-http-payload": "error",
+    "executor/no-schema-class": "error",
     "executor/no-switch-statement": "error",
     "executor/no-ts-nocheck": "error",
     "executor/no-try-catch-or-throw": "error",

apps/cloud/src/mcp-miniflare.e2e.node.test.ts

@@ -47,9 +47,10 @@ import { makeTestBearer } from "./test-bearer";
 // cloud engine consumes is derived from the same types the handlers use.
 // ---------------------------------------------------------------------------
 
-class ApprovedResponse extends Schema.Class<ApprovedResponse>("ApprovedResponse")({
+const ApprovedResponse = Schema.Struct({
   approved: Schema.Boolean,
-}) {}
+});
+type ApprovedResponse = typeof ApprovedResponse.Type;
 
 const ApproveGroup = HttpApiGroup.make("approve").add(
   HttpApiEndpoint.post("approveThing", "/approve", {
@@ -60,7 +61,7 @@ const ApproveGroup = HttpApiGroup.make("approve").add(
 const UpstreamApi = HttpApi.make("approveApi").add(ApproveGroup);
 
 const ApproveHandlers = HttpApiBuilder.group(UpstreamApi, "approve", (h) =>
-  h.handle("approveThing", () => Effect.succeed(new ApprovedResponse({ approved: true }))),
+  h.handle("approveThing", () => Effect.succeed(ApprovedResponse.make({ approved: true }))),
 );
 
 const UpstreamApiLive = HttpApiBuilder.layer(UpstreamApi).pipe(Layer.provide(ApproveHandlers));

apps/cloud/src/mcp-session.e2e.node.test.ts

@@ -68,7 +68,7 @@ const elicitingTestPlugin = definePlugin(() => ({
           }) =>
             Effect.gen(function* () {
               const response = yield* elicit(
-                new FormElicitation({
+                FormElicitation.make({
                   message: "Approve?",
                   requestedSchema: {
                     type: "object",
@@ -106,7 +106,7 @@ const buildScopedExecutor = (scopeId: string, scopeName: string, options: BuildO
     const schema = collectSchemas(plugins);
     const adapter = makePostgresAdapter({ db, schema });
     const blobs = makePostgresBlobStore({ db });
-    const scope = new Scope({
+    const scope = Scope.make({
       id: ScopeId.make(scopeId),
       name: scopeName,
       createdAt: new Date(),

apps/cloud/src/services/__test-harness__/api-harness.ts

@@ -73,12 +73,12 @@ const createTestScopedExecutor = (userId: string, orgId: string, orgName: string
     const schema = collectSchemas(plugins);
     const adapter = makePostgresAdapter({ db, schema });
     const blobs = makePostgresBlobStore({ db });
-    const orgScope = new Scope({
+    const orgScope = Scope.make({
       id: ScopeId.make(orgId),
       name: orgName,
       createdAt: new Date(),
     });
-    const userOrgScope = new Scope({
+    const userOrgScope = Scope.make({
       id: ScopeId.make(userOrgScopeId(userId, orgId)),
       name: `Personal · ${orgName}`,
       createdAt: new Date(),

apps/cloud/src/services/executor.ts

@@ -71,12 +71,12 @@ export const createScopedExecutor = (
     const adapter = makePostgresAdapter({ db, schema });
     const blobs = makePostgresBlobStore({ db });
 
-    const orgScope = new Scope({
+    const orgScope = Scope.make({
       id: ScopeId.make(organizationId),
       name: organizationName,
       createdAt: new Date(),
     });
-    const userOrgScope = new Scope({
+    const userOrgScope = Scope.make({
       id: ScopeId.make(`user-org:${userId}:${organizationId}`),
       name: `Personal · ${organizationName}`,
       createdAt: new Date(),

apps/local/src/server/config-sync.boot.test.ts

@@ -152,12 +152,12 @@ describe("syncFromConfig — MCP auth replay", () => {
       const executor = yield* makeExecutor();
       const connectionId = ConnectionId.make("mcp-oauth2-linear");
       yield* executor.connections.create(
-        new CreateConnectionInput({
+        CreateConnectionInput.make({
           id: connectionId,
           scope: TEST_SCOPE,
           provider: OAUTH2_PROVIDER_KEY,
           identityLabel: "user@example.com",
-          accessToken: new TokenMaterial({
+          accessToken: TokenMaterial.make({
             secretId: SecretId.make(`${connectionId}.access_token`),
             name: "MCP Access Token",
             value: "access-token-value",

apps/local/src/server/executor.ts

@@ -307,7 +307,7 @@ const createLocalExecutorLayer = () => {
       const adapter = makeSqliteAdapter({ db, schema });
       const blobs = makeSqliteBlobStore({ db });
 
-      const scope = new Scope({
+      const scope = Scope.make({
         id: ScopeId.make(scopeId),
         name: cwd,
         createdAt: new Date(),

apps/local/src/server/mcp-oauth.test.ts

@@ -246,7 +246,7 @@ const startHarness = async (tmpDir: string): Promise<Harness> => {
   const adapter = makeSqliteAdapter({ db, schema });
   const blobs = makeSqliteBlobStore({ db });
 
-  const scope = new Scope({
+  const scope = Scope.make({
     id: ScopeId.make(scopeId),
     name: "test",
     createdAt: new Date(),

apps/local/src/server/migrate-connections.ts

@@ -252,7 +252,7 @@ const insertOpenApiCredentialBinding = (
 
 const OAuth2Flow = Schema.Literals(["authorizationCode", "clientCredentials"]);
 
-class LegacyOpenApiOAuth2 extends Schema.Class<LegacyOpenApiOAuth2>("LegacyOpenApiOAuth2")({
+const LegacyOpenApiOAuth2 = Schema.Struct({
   kind: Schema.Literal("oauth2"),
   securitySchemeName: Schema.String,
   flow: OAuth2Flow,
@@ -265,7 +265,8 @@ class LegacyOpenApiOAuth2 extends Schema.Class<LegacyOpenApiOAuth2>("LegacyOpenA
   expiresAt: Schema.NullOr(Schema.Number),
   scope: Schema.NullOr(Schema.String),
   scopes: Schema.Array(Schema.String),
-}) {}
+});
+type LegacyOpenApiOAuth2 = typeof LegacyOpenApiOAuth2.Type;
 
 const decodeOpenApiCurrent = Schema.decodeUnknownOption(OAuth2SourceConfig);
 const decodeOpenApiLegacy = decodeUnknownOptionAs<LegacyOpenApiOAuth2>(LegacyOpenApiOAuth2);

examples/all-plugins/src/main.ts

@@ -47,7 +47,7 @@ import { workosVaultPlugin } from "@executor-js/plugin-workos-vault";
 // SourceRegistry, SecretStore, and PolicyEngine service instances.
 // ---------------------------------------------------------------------------
 
-const scope = new Scope({
+const scope = Scope.make({
   id: ScopeId.make("example-scope"),
   name: "/tmp/example-workspace",
   createdAt: new Date(),
@@ -203,7 +203,7 @@ const program = Effect.gen(function* () {
   console.log("Registered providers:", providers);
 
   yield* executor.secrets.set(
-    new SetSecretInput({
+    SetSecretInput.make({
       id: SecretId.make("example-api-token"),
       scope: "example-scope" as SetSecretInput["scope"],
       name: "Example API Token",