Runtime validation by Takeno · Pull Request #3333 · garden-co/jazz

Takeno · 2026-01-06T16:57:28Z

Description

Cursor's summary is almost complete. Although the scope is clear and documented on Linear, here are the known weird behaviours:

Validations are applied only to writes: invalid data may still exist and be loaded from cojson. Once loaded, the schema validation is applied again to any mutation.
Inputs can be transformed by validators
As validations are not applied on loading, it might happen to set a non-validated comap as a reference inside another CoValue. E.g.

const Box = co.map({x: z.number()});
const Boxes = co.list(Box);

const invalidBox = Box.create({}, {validation: "loose"});

const list = Boxes.create([invalidBox])); // This will not throw
Boxes.create([co.map({}).create({})); // This doesn't either, only the type is checked (CoMap) and uses the reference.

Check this conversation too.

Until the moment we change the default validation mode to "strict", default validation is set to "warn" and an additional console.warn reminds users that the default will be "strict" in the next major release.
~~z.default() now works as expected on writes. They don't work on reads. This is a nice feature, but it can be misunderstood.~~

Still missing

Docs

Note

High Risk
Touches core CoValue mutation paths and schema runtime internals; behavior changes (validation, new defaults/warnings, descriptor resolution) can break apps or tests and may surface new runtime errors during writes.

Overview
Introduces runtime schema validation on writes for schema-based CoValues (CoMap, CoList, CoFeed, plus related built-ins), with a new global setDefaultValidationMode() and per-mutation validation option to enforce strict vs loose behavior (global default is currently warn, logging instead of throwing).

CoValue implementations are refactored to source descriptors/validation schemas from attached coValueSchema objects (initialized for built-ins), adding validation plumbing across create/set/push/splice/applyDiff and updating tests/docs/examples to opt into strict validation. Legacy schema exports coField and Encoders are removed, completing the migration to co/zod-based schema descriptors; better-auth adapter creation paths were adjusted to satisfy the new schema expectations (e.g., initializing _deleted and sessions fields).

^{Written by Cursor Bugbot for commit 507f325. This will update automatically on new commits. Configure here.}

vercel · 2026-01-06T16:57:34Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-demo	Ready	Preview, Comment	Feb 13, 2026 1:55pm
design-system	Error		Feb 13, 2026 1:55pm
file-upload-demo	Ready	Preview, Comment	Feb 13, 2026 1:55pm
form-demo	Ready	Preview, Comment	Feb 13, 2026 1:55pm
gcmp-homepage	Ready	Preview, Comment	Feb 13, 2026 1:55pm
image-upload-demo	Ready	Preview, Comment	Feb 13, 2026 1:55pm
jazz-chat	Ready	Preview, Comment	Feb 13, 2026 1:55pm
jazz-chat-1	Ready	Preview, Comment	Feb 13, 2026 1:55pm
jazz-chat-2	Ready	Preview, Comment	Feb 13, 2026 1:55pm
jazz-filestream	Ready	Preview, Comment	Feb 13, 2026 1:55pm
jazz-image-upload	Ready	Preview, Comment	Feb 13, 2026 1:55pm
jazz-inspector	Ready	Preview, Comment	Feb 13, 2026 1:55pm
jazz-multi-cursors	Ready	Preview, Comment	Feb 13, 2026 1:55pm
jazz-nextjs	Ready	Preview, Comment	Feb 13, 2026 1:55pm
jazz-organization	Ready	Preview, Comment	Feb 13, 2026 1:55pm
jazz-paper-scissors	Ready	Preview, Comment	Feb 13, 2026 1:55pm
jazz-richtext	Ready	Preview, Comment	Feb 13, 2026 1:55pm
jazz-todo	Ready	Preview, Comment	Feb 13, 2026 1:55pm
jazz-vector-search	Ready	Preview, Comment	Feb 13, 2026 1:55pm
jazz-version-history	Ready	Preview, Comment	Feb 13, 2026 1:55pm
music-demo	Ready	Preview, Comment	Feb 13, 2026 1:55pm
passkey-demo	Ready	Preview, Comment	Feb 13, 2026 1:55pm
passphrase-auth-demo	Ready	Preview, Comment	Feb 13, 2026 1:55pm
quint-ui	Ready	Preview, Comment	Feb 13, 2026 1:55pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
jazz-homepage	Ignored	Preview	Feb 13, 2026 1:55pm

nrainhart

Great work! I know this is still a draft, but I couldn't stop myself from leaving a bunch of comments 😅

packages/jazz-tools/src/tools/implementation/zodSchema/schemaTypes/RichTextSchema.ts

packages/jazz-tools/src/tools/implementation/zodSchema/schemaTypes/CoOptionalSchema.ts

packages/jazz-tools/src/tools/implementation/zodSchema/schemaTypes/CoListSchema.ts

packages/jazz-tools/src/tools/implementation/zodSchema/schemaTypes/schemaValidators.ts

packages/jazz-tools/src/tools/implementation/zodSchema/schemaTypes/CoMapSchema.ts

...zz-tools/src/tools/implementation/zodSchema/runtimeConverters/coValueSchemaTransformation.ts

nrainhart · 2026-01-20T02:14:51Z

packages/jazz-tools/src/tools/coValues/coMap.ts

Are there any other zod constructs we should ignore? E.g. transforms & default values

Takeno · 2026-01-20T16:55:55Z

Rebased with 0.19.22 for pre-release publish

…ueSchema handling

… in CoList, CoFeed, CoMap, and Account schemas

…ng in CoFeed, CoList, and schemaUnion

…ueSchema retrieval and enhancing return structure

…lueSchemaTransformation

feat: remove legacy coField schema

cursor

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

cursor · 2026-02-11T19:11:58Z

packages/jazz-tools/src/tools/implementation/zodSchema/schemaTypes/schemaValidators.ts

Union schema detection uses wrong property

High Severity

isUnionSchema checks schema.type === "union" instead of the runtime definition field used elsewhere (schema.def.type). This can make extractFieldShapeFromUnionSchema and extractFieldElementFromUnionSchema reject valid union schemas, which then either disables per-field validation in coMap mutations or throws non-validation errors in coList/coFeed mutations.

Additional Locations (2)

packages/jazz-tools/src/tools/coValues/coList.ts#L560-L563

packages/jazz-tools/src/tools/coValues/coMap.ts#L624-L629

packages/jazz-tools/src/tools/coValues/profile.ts

cursor

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

cursor · 2026-02-12T10:24:23Z

packages/jazz-tools/src/tools/coValues/coList.ts


    for (const [from, to, insert] of patches.reverse()) {
-      this.splice(from, to - from, ...insert);
+      this.spliceLoose(from, to - from, ...insert);


CoList diff updates skip validation

Medium Severity

CoList.$jazz.applyDiff now calls spliceLoose, which bypasses runtime schema checks. This makes a write path mutate lists without validation, even when global mode is strict. Invalid data can be written through applyDiff, diverging from the new validation behavior for normal mutators.

cursor · 2026-02-12T10:24:23Z

packages/jazz-tools/src/tools/coValues/schemaUnion.ts

+      return ResolvedClass.fromRaw(raw);
+    }
+  } as unknown as SchemaUnionConcreteSubclass<V>;
+}


SchemaUnion public factory removed unexpectedly

High Severity

The commit removes SchemaUnion.Of from SchemaUnion and only keeps schemaUnionClassFromDiscriminator as a standalone helper. Existing consumers calling SchemaUnion.Of(...) lose the public API at runtime, which is a breaking behavior change not reflected in the PR’s stated migration scope.

cursor

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

cursor · 2026-02-12T10:48:30Z

.changeset/smooth-lions-joke.md

+"jazz-tools": patch
+---
+
+Removed the legacy `coField` and `Encoders` exports and completed the runtime schema migration to the new schema descriptors. Apps still using the old schema APIs should migrate to the current `co`/zod based schemas.


Breaking release labeled as patch

Medium Severity

The changeset marks jazz-tools as patch while documenting removal of legacy exports (coField, Encoders). Removing public exports is a breaking API change, so this release metadata can publish incompatible behavior under a non-breaking version bump.

cursor · 2026-02-12T10:48:30Z

packages/jazz-tools/src/tools/coValues/coList.ts

-    return class CoListOf extends CoList<Item> {
-      [coField.items] = item;
-    };
-  }


CoList.of guard was unintentionally removed

Low Severity

CoList no longer overrides static of, so CoList.of() now falls back to Array.of. That path bypasses the prior explicit safeguard and can construct non-initialized CoList instances (or throw cryptic constructor errors), re-exposing an API path that was intentionally blocked.

cursor

Cursor Bugbot has reviewed your changes and found 3 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

cursor · 2026-02-12T11:00:51Z

packages/jazz-tools/src/tools/implementation/zodSchema/unionUtils.ts

+            createCoreCoMapSchema(augmentedShape, optionDef.catchall),
+          );
+
+          return augmentedSchema.getCoValueClass() as typeof CoMap;


Union branch class identity lost

High Severity

When schemaUnionDiscriminatorFor needs dummy keys, it now builds a new class from createCoreCoMapSchema(...) instead of extending the matched branch class. Returned values are no longer instances of the original union option class, so branch-specific methods/prototype checks can silently break after co.discriminatedUnion(...) resolution.

cursor · 2026-02-12T11:00:51Z

packages/jazz-tools/src/tools/coValues/schemaUnion.ts

- * class BaseWidget extends CoMap {
- *   type = coField.string;
- * }
- *


SchemaUnion factory API removed unexpectedly

High Severity

SchemaUnion is still publicly exported, but SchemaUnion.Of(...) was removed and the remaining static methods throw Not implemented. Existing consumers using the exported union API can no longer construct usable union classes, causing runtime failures after upgrade.

Additional Locations (1)

packages/jazz-tools/src/tools/exports.ts#L19-L20

packages/jazz-tools/src/tools/coValues/coMap.ts

cursor

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

cursor · 2026-02-12T13:35:26Z

packages/jazz-tools/src/tools/implementation/zodSchema/unionUtils.ts

+            createCoreCoMapSchema(augmentedShape, optionDef.catchall),
+          );
+
+          return augmentedSchema.getCoValueClass() as typeof CoMap;


Union branch class metadata dropped

Medium Severity

When adding dummy fields for co.discriminatedUnion, the discriminator now returns a new class from createCoreCoMapSchema(...) instead of extending the matched option class. This drops option-specific schema metadata like permissions, resolveQuery, and class-level behavior for that branch.

packages/jazz-tools/src/tools/coValues/coList.ts

* chore: replaced union with superRefine in schema validation * fixup! chore: replaced union with superRefine in schema validation

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

packages/jazz-tools/src/tools/coValues/coMap.ts

vercel bot deployed to Preview – jazz-vector-search January 6, 2026 17:37 View deployment

vercel bot had a problem deploying to Preview – jazz-nextjs January 6, 2026 17:38 Failure

This comment has been minimized.

Sign in to view

vercel bot had a problem deploying to Preview – jazz-nextjs January 12, 2026 14:15 Failure

vercel bot had a problem deploying to Preview – jazz-vector-search January 12, 2026 14:17 Failure

Takeno force-pushed the feat/runtime-validation-write branch from f0da92c to adffbfb Compare January 12, 2026 14:32

vercel bot deployed to Preview – jazz-vector-search January 12, 2026 14:37 View deployment

This comment has been minimized.

Sign in to view

vercel bot deployed to Preview – jazz-nextjs January 12, 2026 14:39 View deployment

vercel bot had a problem deploying to Preview – jazz-nextjs January 13, 2026 16:42 Failure

vercel bot had a problem deploying to Preview – jazz-vector-search January 13, 2026 16:44 Failure

vercel bot deployed to Preview – jazz-vector-search January 13, 2026 17:29 View deployment

vercel bot deployed to Preview – jazz-nextjs January 13, 2026 17:29 View deployment

This comment has been minimized.

Sign in to view

vercel bot deployed to Preview – jazz-vector-search January 19, 2026 13:26 View deployment

vercel bot deployed to Preview – jazz-vector-search January 19, 2026 13:31 View deployment

vercel bot deployed to Preview – jazz-vector-search January 19, 2026 19:19 View deployment

nrainhart reviewed Jan 20, 2026

View reviewed changes

vercel bot deployed to Preview – jazz-vector-search January 20, 2026 12:48 View deployment

vercel bot deployed to Preview – jazz-vector-search January 20, 2026 16:26 View deployment

Takeno added the pre-release label Jan 20, 2026

Takeno force-pushed the feat/runtime-validation-write branch from d5879e1 to 34ac5a2 Compare January 20, 2026 16:54

Takeno marked this pull request as ready for review January 20, 2026 16:55

vercel bot deployed to Preview – jazz-vector-search January 20, 2026 17:00 View deployment

This comment was marked as outdated.

Sign in to view

vercel bot deployed to Preview – jazz-vector-search January 20, 2026 17:41 View deployment

This comment was marked as outdated.

Sign in to view

vercel bot deployed to Preview – jazz-vector-search January 20, 2026 18:40 View deployment

gdorsi and others added 12 commits February 11, 2026 12:07

feat: remove legacy _schema

12b4f92

feat: initialize built-in schemas for CoMap and Account, update coVal…

0791cf4

…ueSchema handling

refactor: replace resolveSchemaField with cached getDescriptorsSchema…

fd80743

… in CoList, CoFeed, CoMap, and Account schemas

refactor: remove deprecated methods and streamline SchemaUnion handli…

cca0969

…ng in CoFeed, CoList, and schemaUnion

fix: clean up type castings for schema

ef4fe05

refactor: optimize schemaUnionDiscriminatorFor by consolidating coVal…

dcd2fc7

…ueSchema retrieval and enhancing return structure

refactor: rename imported classes for clarity and consistency in coVa…

d6fa434

…lueSchemaTransformation

chore: assertCoValueSchema typed

8eb0b75

fix: clean up schema builtin checks

5b880c1

refactor: rename coValueClass subclasses as workaround for bundling bug

554f059

chore: changelog

1317e90

Merge pull request #3455 from garden-co/feat/goodbye-cofield-

28358f7

feat: remove legacy coField schema

vercel bot deployed to Preview – jazz-vector-search February 11, 2026 19:10 View deployment

cursor bot reviewed Feb 11, 2026

View reviewed changes

fix: profile default schema using an hydrated schema def

734c671

cursor bot reviewed Feb 12, 2026

View reviewed changes

doc warning about schema validation

b641d1a

vercel bot deployed to Preview – jazz-vector-search February 12, 2026 10:26 View deployment

Takeno added 2 commits February 12, 2026 11:37

fix verify schema.def.type in isUnionSchema

5b15ff3

feat: added local validation mode to coList.applyDiff

d692a24

cursor bot reviewed Feb 12, 2026

View reviewed changes

vercel bot deployed to Preview – jazz-vector-search February 12, 2026 10:50 View deployment

changeset

cdcdad1

cursor bot reviewed Feb 12, 2026

View reviewed changes

chore: refactoring coValueCreateOption (#3457)

1d90cb3

vercel bot deployed to Preview – jazz-vector-search February 12, 2026 13:33 View deployment

cursor bot reviewed Feb 12, 2026

View reviewed changes

Schema validation with superRefine (#3460)

507f325

* chore: replaced union with superRefine in schema validation * fixup! chore: replaced union with superRefine in schema validation

vercel bot deployed to Preview – jazz-vector-search February 13, 2026 13:55 View deployment

cursor bot reviewed Feb 13, 2026

View reviewed changes

packages/jazz-tools/src/tools/coValues/coMap.ts Show resolved Hide resolved

Conversation

Takeno commented Jan 6, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Still missing

Uh oh!

vercel bot commented Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

nrainhart left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nrainhart Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Takeno commented Jan 20, 2026

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Feb 11, 2026

Choose a reason for hiding this comment

Union schema detection uses wrong property

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Feb 12, 2026

Choose a reason for hiding this comment

CoList diff updates skip validation

Uh oh!

cursor bot Feb 12, 2026

Choose a reason for hiding this comment

SchemaUnion public factory removed unexpectedly

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Feb 12, 2026

Choose a reason for hiding this comment

Breaking release labeled as patch

Uh oh!

cursor bot Feb 12, 2026

Choose a reason for hiding this comment

CoList.of guard was unintentionally removed

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Feb 12, 2026

Choose a reason for hiding this comment

Union branch class identity lost

Uh oh!

cursor bot Feb 12, 2026

Choose a reason for hiding this comment

SchemaUnion factory API removed unexpectedly

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Feb 12, 2026

Choose a reason for hiding this comment

Union branch class metadata dropped

Uh oh!

Takeno commented Jan 6, 2026 •

edited by cursor bot

Loading

vercel bot commented Jan 6, 2026 •

edited

Loading