@confect/core 9.2.3 → 10.0.0-next.0

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@confect/core",
   "description": "Shared specs and schemas used by all Confect packages",
-  "version": "9.2.3",
+  "version": "10.0.0-next.0",
   "author": "RJ Dellecese",
   "bugs": {
     "url": "https://github.com/rjdellecese/confect/issues"
   },
   "devDependencies": {
     "@ark/attest": "0.56.0",
-    "@effect/vitest": "0.29.0",
+    "@effect/vitest": "4.0.0-beta.97",
     "@types/node": "25.3.3",
-    "effect": "3.21.2",
+    "effect": "4.0.0-beta.97",
     "tsdown": "0.20.3",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
@@ -49,7 +49,7 @@
   "module": "./dist/index.js",
   "peerDependencies": {
     "convex": "^1.32.0",
-    "effect": "^3.21.2"
+    "effect": "^4.0.0-beta.97"
   },
   "repository": {
     "type": "git",

package/src/FunctionProvenance.ts

@@ -5,9 +5,9 @@ import * as Lazy from "./Lazy";
 
 export type FunctionProvenance = Data.TaggedEnum<{
   Confect: {
-    args: Schema.Schema.AnyNoContext;
-    returns: Schema.Schema.AnyNoContext;
-    error?: Schema.Schema.AnyNoContext;
+    args: Schema.Codec<any, any>;
+    returns: Schema.Codec<any, any>;
+    error?: Schema.Codec<any, any>;
   };
   Convex: {
     /** @internal */
@@ -18,9 +18,9 @@ export type FunctionProvenance = Data.TaggedEnum<{
 }>;
 
 export interface Confect<
-  Args extends Schema.Schema.AnyNoContext,
-  Returns extends Schema.Schema.AnyNoContext,
-  Error extends Schema.Schema.AnyNoContext = never,
+  Args extends Schema.Codec<any, any>,
+  Returns extends Schema.Codec<any, any>,
+  Error extends Schema.Codec<any, any> = never,
 > {
   readonly _tag: "Confect";
   readonly args: Args;
@@ -29,9 +29,9 @@ export interface Confect<
 }
 
 export interface AnyConfect extends Confect<
-  Schema.Schema.AnyNoContext,
-  Schema.Schema.AnyNoContext,
-  Schema.Schema.AnyNoContext
+  Schema.Codec<any, any>,
+  Schema.Codec<any, any>,
+  Schema.Codec<any, any>
 > {}
 
 export interface Convex<Args extends DefaultFunctionArgs, Returns> {
@@ -61,9 +61,9 @@ export const FunctionProvenance = Data.taggedEnum<FunctionProvenance>();
  * relies on `Data`'s structural `Equal`/`Hash` for provenance values.
  */
 export const Confect = <
-  Args extends Schema.Schema.AnyNoContext,
-  Returns extends Schema.Schema.AnyNoContext,
-  Error extends Schema.Schema.AnyNoContext = never,
+  Args extends Schema.Codec<any, any>,
+  Returns extends Schema.Codec<any, any>,
+  Error extends Schema.Codec<any, any> = never,
 >(
   args: () => Args,
   returns: () => Returns,

package/src/FunctionSpec.ts

@@ -93,7 +93,7 @@ export type Name<FunctionSpec_ extends AnyWithProps> = FunctionSpec_["name"];
 export type Args<FunctionSpec_ extends AnyWithProps> = FunctionSpec_ extends {
   functionProvenance: {
     _tag: "Confect";
-    args: infer ArgsSchema_ extends Schema.Schema.AnyNoContext;
+    args: infer ArgsSchema_ extends Schema.Codec<any, any>;
   };
 }
   ? ArgsSchema_["Type"]
@@ -107,7 +107,7 @@ export type Returns<FunctionSpec_ extends AnyWithProps> =
   FunctionSpec_ extends {
     functionProvenance: {
       _tag: "Confect";
-      returns: infer ReturnsSchema_ extends Schema.Schema.AnyNoContext;
+      returns: infer ReturnsSchema_ extends Schema.Codec<any, any>;
     };
   }
     ? ReturnsSchema_["Type"]
@@ -121,7 +121,7 @@ export type EncodedArgs<FunctionSpec_ extends AnyWithProps> =
   FunctionSpec_ extends {
     functionProvenance: {
       _tag: "Confect";
-      args: infer ArgsSchema_ extends Schema.Schema.AnyNoContext;
+      args: infer ArgsSchema_ extends Schema.Codec<any, any>;
     };
   }
     ? ArgsSchema_["Encoded"]
@@ -135,7 +135,7 @@ export type EncodedReturns<FunctionSpec_ extends AnyWithProps> =
   FunctionSpec_ extends {
     functionProvenance: {
       _tag: "Confect";
-      returns: infer ReturnsSchema_ extends Schema.Schema.AnyNoContext;
+      returns: infer ReturnsSchema_ extends Schema.Codec<any, any>;
     };
   }
     ? ReturnsSchema_["Encoded"]
@@ -149,7 +149,7 @@ export type Error<FunctionSpec_ extends AnyWithProps> = FunctionSpec_ extends {
   functionProvenance: FunctionProvenance.Confect<
     any,
     any,
-    infer ErrorSchema_ extends Schema.Schema.AnyNoContext
+    infer ErrorSchema_ extends Schema.Codec<any, any>
   >;
 }
   ? ErrorSchema_["Type"]
@@ -160,7 +160,7 @@ export type EncodedError<FunctionSpec_ extends AnyWithProps> =
     functionProvenance: FunctionProvenance.Confect<
       any,
       any,
-      infer ErrorSchema_ extends Schema.Schema.AnyNoContext
+      infer ErrorSchema_ extends Schema.Codec<any, any>
     >;
   }
     ? ErrorSchema_["Encoded"]
@@ -215,9 +215,9 @@ const make =
   ) =>
   <
     const Name_ extends string,
-    Args_ extends Schema.Schema.AnyNoContext,
-    Returns_ extends Schema.Schema.AnyNoContext,
-    Error_ extends Schema.Schema.AnyNoContext = never,
+    Args_ extends Schema.Codec<any, any>,
+    Returns_ extends Schema.Codec<any, any>,
+    Error_ extends Schema.Codec<any, any> = never,
   >({
     name,
     args,

package/src/GenericId.ts

@@ -1,20 +1,20 @@
 import type { GenericId as ConvexGenericId } from "convex/values";
-import type { Option } from "effect";
+import * as Option from "effect/Option";
 import * as Schema from "effect/Schema";
 import * as SchemaAST from "effect/SchemaAST";
 
-const ConvexId = Symbol.for("ConvexId");
+const ConvexId = "~@confect/core/ConvexId";
 
 export const GenericId = <TableName extends string>(
   tableName: TableName,
-): Schema.Schema<ConvexGenericId<TableName>> =>
-  Schema.String.pipe(
-    Schema.annotations({ [ConvexId]: tableName }),
-  ) as unknown as Schema.Schema<ConvexGenericId<TableName>>;
+): Schema.Codec<ConvexGenericId<TableName>> =>
+  Schema.String.annotate({
+    [ConvexId]: tableName,
+  }) as unknown as Schema.Codec<ConvexGenericId<TableName>>;
 
 export type GenericId<TableName extends string> = ConvexGenericId<TableName>;
 
 export const tableName = <TableName extends string>(
   ast: SchemaAST.AST,
 ): Option.Option<TableName> =>
-  SchemaAST.getAnnotation<TableName>(ConvexId)(ast);
+  Option.fromNullishOr(SchemaAST.resolveAt<TableName>(ConvexId)(ast));

package/src/PaginationResult.ts

@@ -1,21 +1,18 @@
 import * as Schema from "effect/Schema";
 
-export const PaginationResult = <Doc extends Schema.Schema.AnyNoContext>(
+export const PaginationResult = <Doc extends Schema.Codec<any, any>>(
   Doc: Doc,
 ) =>
   Schema.Struct({
     page: Schema.mutable(Schema.Array(Doc)),
     isDone: Schema.Boolean,
     continueCursor: Schema.String,
-    splitCursor: Schema.optionalWith(Schema.Union(Schema.String, Schema.Null), {
-      exact: true,
-    }),
-    pageStatus: Schema.optionalWith(
-      Schema.Union(
+    splitCursor: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    pageStatus: Schema.optionalKey(
+      Schema.Union([
         Schema.Literal("SplitRecommended"),
         Schema.Literal("SplitRequired"),
         Schema.Null,
-      ),
-      { exact: true },
+      ]),
     ),
   });

package/src/Ref.ts

@@ -5,7 +5,6 @@ import type {
 import { makeFunctionReference } from "convex/server";
 import type { Value } from "convex/values";
 import { ConvexError } from "convex/values";
-import type { ParseResult } from "effect";
 import * as Effect from "effect/Effect";
 import * as Match from "effect/Match";
 import * as Option from "effect/Option";
@@ -224,10 +223,10 @@ export const hasErrorSchema = (ref: Any): boolean =>
 export const encodeArgs = <Ref_ extends Any>(
   ref: Ref_,
   args: Args<Ref_>,
-): Effect.Effect<unknown, ParseResult.ParseError> =>
+): Effect.Effect<unknown, Schema.SchemaError> =>
   Match.value(ref.functionSpec.functionProvenance).pipe(
     Match.tag("Confect", (confectFunctionProvenance) =>
-      Schema.encode(confectFunctionProvenance.args)(args),
+      Schema.encodeEffect(confectFunctionProvenance.args)(args),
     ),
     Match.tag("Convex", () => Effect.succeed(args)),
     Match.exhaustive,
@@ -236,10 +235,10 @@ export const encodeArgs = <Ref_ extends Any>(
 export const decodeReturns = <Ref_ extends Any>(
   ref: Ref_,
   returns: unknown,
-): Effect.Effect<Returns<Ref_>, ParseResult.ParseError> =>
+): Effect.Effect<Returns<Ref_>, Schema.SchemaError> =>
   Match.value(ref.functionSpec.functionProvenance).pipe(
     Match.tag("Confect", (confectFunctionProvenance) =>
-      Schema.decode(confectFunctionProvenance.returns)(returns),
+      Schema.decodeUnknownEffect(confectFunctionProvenance.returns)(returns),
     ),
     Match.tag("Convex", () => Effect.succeed(returns)),
     Match.exhaustive,
@@ -263,7 +262,7 @@ export const decodeArgsSync = <Ref_ extends Any>(
 ): Args<Ref_> =>
   Match.value(ref.functionSpec.functionProvenance).pipe(
     Match.tag("Confect", (confectFunctionProvenance) =>
-      Schema.decodeSync(confectFunctionProvenance.args)(encodedArgs),
+      Schema.decodeUnknownSync(confectFunctionProvenance.args)(encodedArgs),
     ),
     Match.tag("Convex", () => encodedArgs),
     Match.exhaustive,
@@ -287,7 +286,9 @@ export const decodeReturnsSync = <Ref_ extends Any>(
 ): Returns<Ref_> =>
   Match.value(ref.functionSpec.functionProvenance).pipe(
     Match.tag("Confect", (confectFunctionProvenance) =>
-      Schema.decodeSync(confectFunctionProvenance.returns)(encodedReturns),
+      Schema.decodeUnknownSync(confectFunctionProvenance.returns)(
+        encodedReturns,
+      ),
     ),
     Match.tag("Convex", () => encodedReturns),
     Match.exhaustive,
@@ -332,12 +333,14 @@ export const decodeErrorOrElse =
 export const decodeError = <Ref_ extends Any>(
   ref: Ref_,
   encodedError: unknown,
-): Effect.Effect<Option.Option<Error<Ref_>>, ParseResult.ParseError> =>
+): Effect.Effect<Option.Option<Error<Ref_>>, Schema.SchemaError> =>
   Match.value(ref.functionSpec.functionProvenance).pipe(
     Match.tag("Confect", (confectFunctionProvenance) =>
       "error" in confectFunctionProvenance
         ? Effect.map(
-            Schema.decode(confectFunctionProvenance.error)(encodedError),
+            Schema.decodeUnknownEffect(confectFunctionProvenance.error)(
+              encodedError,
+            ),
             Option.some,
           )
         : Effect.succeed(Option.none<Error<Ref_>>()),
@@ -358,7 +361,7 @@ export const decodeErrorSync = <Ref_ extends Any>(
     Match.tag("Confect", (confectFunctionProvenance) =>
       "error" in confectFunctionProvenance
         ? Option.some(
-            Schema.decodeSync(confectFunctionProvenance.error)(
+            Schema.decodeUnknownSync(confectFunctionProvenance.error)(
               encodedError,
             ) as Error<Ref_>,
           )
@@ -376,7 +379,9 @@ export const maybeDecodeErrorSync = <Ref_ extends Any>(
     ? Match.value(ref.functionSpec.functionProvenance).pipe(
         Match.tag("Confect", (confectFunctionProvenance) =>
           "error" in confectFunctionProvenance
-            ? Schema.decodeSync(confectFunctionProvenance.error)(error.data)
+            ? Schema.decodeUnknownSync(confectFunctionProvenance.error)(
+                error.data,
+              )
             : error,
         ),
         Match.tag("Convex", () => error),
@@ -400,7 +405,7 @@ export const runWithCodec = <Ref_ extends Any, E = never>(
     encodedArgs: unknown,
   ) => PromiseLike<unknown>,
   mapUnknownError?: (error: unknown) => E,
-): Effect.Effect<Returns<Ref_>, E | Error<Ref_> | ParseResult.ParseError> =>
+): Effect.Effect<Returns<Ref_>, E | Error<Ref_> | Schema.SchemaError> =>
   Effect.gen(function* () {
     const functionReference = getFunctionReference(ref);
     const functionProvenance = ref.functionSpec.functionProvenance;
@@ -425,13 +430,13 @@ export const runWithCodec = <Ref_ extends Any, E = never>(
     return yield* Match.value(functionProvenance).pipe(
       Match.tag("Confect", (confectFunctionProvenance) =>
         Effect.gen(function* () {
-          const encodedArgs = yield* Schema.encode(
+          const encodedArgs = yield* Schema.encodeEffect(
             confectFunctionProvenance.args,
           )(args);
           const encodedReturns = yield* invoke(encodedArgs);
-          return yield* Schema.decode(confectFunctionProvenance.returns)(
-            encodedReturns,
-          );
+          return yield* Schema.decodeUnknownEffect(
+            confectFunctionProvenance.returns,
+          )(encodedReturns);
         }),
       ),
       Match.tag("Convex", () => invoke(args)),

package/src/Registry.ts

@@ -22,9 +22,9 @@ export interface RegistryItems {
  * Effect's global default-value cache to align two separately-defined tags
  * by string key.
  */
-export class Registry extends Context.Reference<Registry>()(
+export const Registry = Context.Reference<Ref.Ref<RegistryItems>>(
   "@confect/core/Registry",
   {
-    defaultValue: () => Ref.unsafeMake<RegistryItems>({}),
+    defaultValue: () => Ref.makeUnsafe<RegistryItems>({}),
   },
-) {}
+);

package/src/SystemFields.ts

@@ -1,51 +1,280 @@
-import type {
-  Expand,
-  IdField,
-  SystemFields as NonIdSystemFields,
-} from "convex/server";
+import type { IdField, SystemFields as NonIdSystemFields } from "convex/server";
+import { pipe } from "effect/Function";
+import * as Array from "effect/Array";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Predicate from "effect/Predicate";
+import * as Record from "effect/Record";
 import * as Schema from "effect/Schema";
+import * as SchemaAST from "effect/SchemaAST";
+import * as SchemaGetter from "effect/SchemaGetter";
+import * as SchemaTransformation from "effect/SchemaTransformation";
+import * as Struct from "effect/Struct";
 import * as GenericId from "./GenericId";
 
-type SystemFieldsSchema<TableName extends string> = Schema.Struct<{
-  _id: Schema.Schema<
-    GenericId.GenericId<TableName>,
-    GenericId.GenericId<TableName>,
-    never
-  >;
-  _creationTime: typeof Schema.Number;
-}>;
-
 /**
- * Produces a schema for Convex system fields.
+ * Produces a schema for Convex system fields. In Confect, system fields include `_id`.
  */
-export const SystemFields = <TableName extends string>(
-  tableName: TableName,
-): SystemFieldsSchema<TableName> =>
+export const SystemFields = <TableName extends string>(tableName: TableName) =>
   Schema.Struct({
     _id: GenericId.GenericId(tableName),
     _creationTime: Schema.Number,
   });
 
+/**
+ * The field map added to a table schema, derived from {@link SystemFields} so it
+ * stays in lockstep with the runtime schema.
+ */
+type SystemFieldsFor<TableName extends string> = ReturnType<
+  typeof SystemFields<TableName>
+>["fields"];
+
+/**
+ * The system field names, derived from {@link SystemFields} so they stay in
+ * lockstep with the schema.
+ */
+const systemFieldNames: ReadonlyArray<string> = Record.keys(
+  SystemFields("").fields,
+);
+
+const isSystemFieldKey = (key: string | symbol): key is string =>
+  Predicate.isString(key) && Array.contains(systemFieldNames, key);
+
+const splitSystemFields = (input: { [key: PropertyKey]: unknown }) => {
+  const keys = Reflect.ownKeys(input);
+  const pick = (pickedKeys: ReadonlyArray<string | symbol>) =>
+    Record.fromEntries(
+      Array.map(pickedKeys, (key) => [key, input[key]] as const),
+    );
+  return {
+    system: pick(Array.filter(keys, isSystemFieldKey)),
+    rest: pick(Array.filter(keys, Predicate.not(isSystemFieldKey))),
+  };
+};
+
+/**
+ * Wraps a transformation getter so the system fields bypass it: they are split
+ * off the input before the user-defined getter runs and merged back into its
+ * output. Transformations construct fresh objects, so without this the system
+ * fields would be dropped at every transformation step.
+ */
+const wrapGetter = (
+  getter: SchemaGetter.Getter<any, any, any>,
+): SchemaGetter.Getter<any, any, any> =>
+  new SchemaGetter.Getter((input, options) => {
+    if (Option.isNone(input) || !Predicate.isObject(input.value)) {
+      return getter.run(input, options);
+    }
+    const { system, rest } = splitSystemFields(input.value);
+    return getter
+      .run(Option.some(rest), options)
+      .pipe(
+        Effect.map(
+          Option.map((output) =>
+            Predicate.isObject(output) ? Struct.assign(output, system) : output,
+          ),
+        ),
+      );
+  });
+
+const wrapTransformation = (
+  transformation: SchemaAST.Link["transformation"],
+): SchemaTransformation.Transformation<any, any, any, any> => {
+  if (!SchemaTransformation.isTransformation(transformation)) {
+    throw new Error(
+      "Cannot extend a table schema that uses decoding/encoding middleware with system fields",
+    );
+  }
+  return new SchemaTransformation.Transformation(
+    wrapGetter(transformation.decode),
+    wrapGetter(transformation.encode),
+  );
+};
+
+/**
+ * Builds an AST walker that adds the given system-field property signatures to
+ * every object node of a schema's AST — including each step of its encoding
+ * chain — wrapping transformations so the fields survive them.
+ */
+const makeExtendAst = (
+  systemPropertySignatures: ReadonlyArray<SchemaAST.PropertySignature>,
+) => {
+  const extendEncoding = (encoding: SchemaAST.Encoding): SchemaAST.Encoding =>
+    Array.map(
+      encoding,
+      (link) =>
+        new SchemaAST.Link(
+          extendAst(link.to),
+          wrapTransformation(link.transformation),
+        ),
+    );
+
+  const extendAst = (ast: SchemaAST.AST): SchemaAST.AST => {
+    if (SchemaAST.isUnion(ast)) {
+      return new SchemaAST.Union(
+        Array.map(ast.types, extendAst),
+        ast.mode,
+        ast.annotations,
+        ast.checks,
+        ast.encoding === undefined ? undefined : extendEncoding(ast.encoding),
+        ast.context,
+        ast.encodingChecks,
+      );
+    }
+    if (SchemaAST.isSuspend(ast)) {
+      return new SchemaAST.Suspend(
+        () => extendAst(ast.thunk()),
+        ast.annotations,
+        undefined,
+        ast.encoding === undefined ? undefined : extendEncoding(ast.encoding),
+        ast.context,
+      );
+    }
+    if (SchemaAST.isObjects(ast)) {
+      return new SchemaAST.Objects(
+        Array.appendAll(ast.propertySignatures, systemPropertySignatures),
+        ast.indexSignatures,
+        ast.annotations,
+        ast.checks,
+        ast.encoding === undefined ? undefined : extendEncoding(ast.encoding),
+        ast.context,
+        ast.encodingChecks,
+      );
+    }
+    throw new Error(
+      ast._tag === "Declaration"
+        ? "Cannot extend a `Declaration` schema (such as a `Schema.Class`) with system fields: its decoded values are constructed instances, which cannot gain extra fields. Use a plain `Schema.Struct`, or transform to one with `Schema.decodeTo`."
+        : `Cannot extend a \`${ast._tag}\` schema node with system fields: a table schema must resolve to an object shape at every step of its encoding.`,
+    );
+  };
+
+  return extendAst;
+};
+
 /**
  * Extend a table schema with Convex system fields.
+ *
+ * A plain `Struct` gains the fields via `Schema.fieldsAssign` and a `Union`
+ * has them distributed across its members, preserving the schema's
+ * `Struct`/`Union` structure. Any other object-shaped schema — one built with
+ * `Schema.decodeTo`/`Schema.encodeKeys`, a branded struct, a suspended schema
+ * — is extended at the AST level: every object node in its encoding chain
+ * gains the system fields, and each transformation is wrapped so the fields
+ * bypass the user-defined getters. Schemas that do not resolve to an object
+ * shape at every step (such as `Schema.Class`, whose decoded values are class
+ * instances) are rejected with a descriptive error.
+ *
+ * Note that struct-level checks on an extended schema observe the value with
+ * the system fields attached, and encoding an extended schema emits the system
+ * fields alongside the table fields.
  */
 export const extendWithSystemFields = <
   TableName extends string,
-  TableSchema extends Schema.Schema.AnyNoContext,
+  TableSchema extends Schema.Codec<any, any>,
 >(
   tableName: TableName,
   schema: TableSchema,
-): ExtendWithSystemFields<TableName, TableSchema> =>
-  Schema.extend(SystemFields(tableName), schema);
+): ExtendWithSystemFields<TableName, TableSchema> => {
+  const system = SystemFields(tableName).fields;
+
+  const extendAst = makeExtendAst(
+    pipe(
+      system,
+      Record.toEntries,
+      Array.map(
+        ([name, field]) => new SchemaAST.PropertySignature(name, field.ast),
+      ),
+    ),
+  );
+
+  const extend = (s: Schema.Top): Schema.Top => {
+    if (
+      s.ast.encoding === undefined &&
+      SchemaAST.isUnion(s.ast) &&
+      Array.isArray(
+        (s as Partial<Schema.Union<ReadonlyArray<Schema.Top>>>).members,
+      )
+    ) {
+      return Schema.Union(
+        Array.map(
+          (s as Schema.Union<ReadonlyArray<Schema.Top>>).members,
+          extend,
+        ),
+      );
+    }
+    if (
+      s.ast.encoding === undefined &&
+      SchemaAST.isObjects(s.ast) &&
+      typeof (s as Partial<Schema.Struct<Schema.Struct.Fields>>).mapFields ===
+        "function"
+    ) {
+      return Schema.fieldsAssign(system)(
+        s as Schema.Struct<Schema.Struct.Fields>,
+      );
+    }
+    return Schema.make(extendAst(s.ast));
+  };
+
+  return extend(schema) as unknown as ExtendWithSystemFields<
+    TableName,
+    TableSchema
+  >;
+};
+
+/**
+ * Applies the system fields to a single struct, mirroring `Schema.fieldsAssign`.
+ * Any other (already-extended or opaque) schema falls back to a `Codec` carrying
+ * the system-field document shape.
+ */
+type ApplySystemFields<TableName extends string, S> =
+  S extends Schema.Struct<infer Fields extends Schema.Struct.Fields>
+    ? Schema.Struct<
+        Struct.Simplify<Struct.Assign<Fields, SystemFieldsFor<TableName>>>
+      >
+    : S extends Schema.Codec<infer Type, infer Encoded>
+      ? Schema.Codec<
+          WithSystemFields<TableName, Type>,
+          WithSystemFields<TableName, Encoded>
+        >
+      : never;
 
 /**
  * Extend a table schema with Convex system fields at the type level.
+ *
+ * This mirrors the runtime {@link extendWithSystemFields}: a `Struct` gains the
+ * system fields directly (matching `Schema.fieldsAssign`), and a `Union` has
+ * them distributed across its members (matching
+ * `union.mapMembers(Tuple.map(Schema.fieldsAssign(...)))`). The `Struct`/`Union`
+ * structure is preserved rather than collapsed to a bare `Codec`; any other
+ * schema falls back to a `Codec` carrying the system-field document shape,
+ * matching the runtime's AST-level extension.
  */
 export type ExtendWithSystemFields<
   TableName extends string,
-  TableSchema extends Schema.Schema.AnyNoContext,
-> = Schema.extend<SystemFieldsSchema<TableName>, TableSchema>;
+  TableSchema extends Schema.Top,
+> =
+  TableSchema extends Schema.Union<
+    infer Members extends ReadonlyArray<Schema.Top>
+  >
+    ? Schema.Union<
+        Struct.Simplify<
+          Readonly<{
+            [K in keyof Members]: ExtendWithSystemFields<TableName, Members[K]>;
+          }>
+        >
+      >
+    : ApplySystemFields<TableName, TableSchema>;
 
-export type WithSystemFields<TableName extends string, Document> = Expand<
-  Readonly<IdField<TableName>> & Readonly<NonIdSystemFields> & Document
->;
+/**
+ * The decoded/encoded document shape: a table's fields plus Convex's system
+ * fields. Deliberately a bare intersection (no `Expand`/`Simplify`) — flattening
+ * it with a homomorphic mapped type collapses to `{ [x: string]: any }` when
+ * `Document` is still an unresolved generic, which breaks structural
+ * comparability in the database reader/writer plumbing.
+ */
+export type WithSystemFields<
+  TableName extends string,
+  Document,
+> = Document extends unknown
+  ? IdField<TableName> & NonIdSystemFields & Document
+  : never;