Review ZenStack v3 breaking changes documentation

[therealbrad]

Review the official ZenStack v3 breaking changes and migration guide to understand all changes required for the upgrade.

Acceptance Criteria:

• Read through the full v3 migration guide
• Document any project-specific impacts
• Identify any blockers or risks

Part of the ZenStack v2 → v3 upgrade.

[therealbrad]

ZenStack V2 → V3 Migration Analysis for TestPlanIt

Issue: #60 - Review ZenStack v3 breaking changes documentation

Current Version: ZenStack 2.22.2

Target Version: ZenStack V3 3.3.3 (stable, released Feb 6, 2026)

---

Executive Summary

ZenStack V3 is a complete rewrite that replaces Prisma with a custom ORM engine built on Kysely. This is not an incremental upgrade — it fundamentally changes how the ORM works while keeping database schemas backward-compatible (no data migration needed). The migration will touch nearly every layer of TestPlanIt: client instantiation, generated hooks, API handlers, multi-tenant middleware, type imports, and Prisma client extensions.

No hard blockers remain. The @zenstackhq/openapi plugin is not yet available in V3 but the current generated spec can be frozen as a static snapshot and maintained manually. The @core/zod plugin is also unavailable but its generated output is unused in the codebase.

---

1. Breaking Changes with Project-Specific Impact

1.1 Prisma Removal (CRITICAL — Highest Impact)

V3 replaces PrismaClient with ZenStackClient backed by Kysely. This affects:

Area	Scope	Details
@prisma/client type imports	~388 occurrences across ~379 files	Every model type, enum, Prisma namespace usage
PrismaClient references	~177 occurrences across ~54 files	Workers, services, seeds, scripts, tests
enhance() calls	9 files	lib/prisma.ts, API routes, server actions, SyncService
@zenstackhq/runtime imports	93 generated hook files + 12 manual files	All hooks + manual enhance() usage

V2 → V3 Change:

// V2
import { PrismaClient } from '@prisma/client';
import { enhance } from '@zenstackhq/runtime';
const prisma = new PrismaClient();
const db = enhance(prisma, { user });

// V3
import { ZenStackClient } from '@zenstackhq/orm';
import { PostgresDialect } from '@zenstackhq/orm/dialects/postgres';
import { PolicyPlugin } from '@zenstackhq/plugin-policy';
import { schema } from './zenstack/schema';
import { Pool } from 'pg';

const db = new ZenStackClient(schema, {
  dialect: new PostgresDialect({
    pool: new Pool({ connectionString: process.env.DATABASE_URL }),
  }),
});
const authDb = db.$use(new PolicyPlugin()).$setAuth(user);

1.2 Prisma Client Extensions Not Supported (CRITICAL)

File: lib/prisma.ts (~887 lines)

TestPlanIt uses $extends() extensively for:

• Elasticsearch sync on mutations (repositoryCases, testRuns, sessions, etc.)
• Audit logging on all CRUD operations
• Auto-complete logic (e.g., setting completedAt on test run completion)
• User/permission audit on account changes

V3 does not support Prisma Client Extensions. These must be reimplemented as ZenStack V3 runtime plugins using the new plugin system:

// V3 Runtime Plugin Interface
interface RuntimePlugin<Schema> {
  id: string;
  onQuery?: OnQueryCallback<Schema>;           // Intercept ORM queries
  onEntityMutation?: {                         // Before/after mutation hooks
    beforeEntityMutation?(): void;
    afterEntityMutation?(): void;
  };
  onKyselyQuery?: OnKyselyQueryCallback<Schema>; // SQL-level interception
}

The onEntityMutation hooks are the most direct replacement for $extends() behavior. This is a significant rewrite requiring careful testing.

1.3 TanStack Query Hook Pattern Change (HIGH — Major Frontend Impact)

93 generated hook files in lib/hooks/ and hundreds of component-level usages.

V2 → V3 Change:

// V2 - Standalone auto-generated hooks
import { useFindManyTestRuns } from '~/lib/hooks';
const { data } = useFindManyTestRuns({ where: { ... } });

// V3 - Client-based hooks
import { useClientQueries } from '@zenstackhq/tanstack-query/react';
import { schema } from '~/zenstack/schema';

const client = useClientQueries(schema);
const { data } = client.testRuns.useFindMany({ where: { ... } });

Additionally, V3 requires a QuerySettingsProvider:

import { QuerySettingsProvider } from '@zenstackhq/tanstack-query/react';

<QuerySettingsProvider value={{ endpoint: '/api/model' }}>
  <App />
</QuerySettingsProvider>

Every component that imports from ~/lib/hooks/ will need updating. This is the largest surface area change in the migration.

1.4 @password Attribute Removed (MEDIUM)

File: schema.zmodel:80

password String @password @omit @length(4)

The @password attribute (auto-hashing on create/update) is removed in V3 with no built-in replacement. Password hashing must be handled in application code (server actions, API routes).

1.5 @omit Attribute Removed (MEDIUM)

4 usages in schema.zmodel:

password             String   @password @omit @length(4)    // line 80
twoFactorSecret      String?  @omit                         // line 135
twoFactorBackupCodes String?  @omit                         // line 136
passwordHash         String?  @omit                         // line 2889

In V3, @omit is replaced by the omit option in ClientOptions:

const db = new ZenStackClient(schema, {
  dialect: ...,
  omit: {
    user: { password: true, twoFactorSecret: true, twoFactorBackupCodes: true },
    ssoProvider: { passwordHash: true },
  },
});

1.6 future() → before() Policy Syntax Change (LOW)

1 occurrence at schema.zmodel:2847:

// V2
@@allow('update', (auth().id == userId && (future().isRead != isRead || future().isDeleted != isDeleted)) || auth().access == 'ADMIN')

// V3
@@allow('post-update', (auth().id == userId && (isRead != before().isRead || isDeleted != before().isDeleted)) || auth().access == 'ADMIN')

Changes: 'update' → 'post-update', future() → before(), perspective inverted.

1.7 update/delete Policy Rejection Behavior Change (LOW)

In V3, when update or delete operations are rejected by access policies, they throw NotFoundError instead of a forbidden error. This may affect error handling logic in the frontend or API layer.

1.8 Server/API Handler Changes (MEDIUM)

File: app/api/model/[...path]/route.ts (~400 lines)

// V2
import { NextRequestHandler } from "@zenstackhq/server/next";
const handler = NextRequestHandler({ getPrisma, useAppDir: true });

// V3
import { NextRequestHandler } from '@zenstackhq/server/next';
import { RPCApiHandler } from '@zenstackhq/server/api';
import { schema } from '~/zenstack/schema';

const handler = NextRequestHandler({
  apiHandler: new RPCApiHandler({ schema }),
  getClient: (req) => db.$setAuth(getSessionUser(req)),
  useAppDir: true,
});

Key changes: getPrisma → getClient, explicit RPCApiHandler({ schema }), auto-user-injection logic must be reimplemented.

1.9 Multi-Tenant Client Management (MEDIUM)

File: lib/multiTenantPrisma.ts

The per-tenant PrismaClient cache must be reimplemented using per-tenant ZenStackClient instances with separate PostgresDialect connection pools. The core pattern is similar but the client construction changes entirely.

1.10 delegate Enhancement Kind (LOW)

File: lib/integrations/services/SyncService.ts (2 occurrences)

const userDb = enhance(prisma, { user }, { kinds: ["delegate"] });

This V2-specific option needs investigation for V3 equivalent.

1.11 Type Import Changes (HIGH — Automated)

All @prisma/client type imports must change:

// V2
import { User, Post, Prisma } from '@prisma/client';

// V3
import { User, Post } from './zenstack/models';
import { UserFindManyArgs } from './zenstack/input';

~388 occurrences across ~379 files. This can be largely automated with a codemod.

---

2. Plugin Changes

2.1 OpenAPI Plugin (BLOCKER — Not Yet Available in V3)

Current config in schema.zmodel:22-28:

plugin openapi {
    provider = '@zenstackhq/openapi'
    output = './lib/openapi/zenstack-openapi.json'
    title = 'TestPlanIt API'
    version = '1.0.0'
    description = 'Auto-generated API documentation for ZenStack data models'
    prefix = '/api/model'
}

@zenstackhq/openapi is planned for redesign but not available in V3. TestPlanIt generates an 18.3 MB OpenAPI spec used for API documentation. Mitigation: Freeze the current generated zenstack-openapi.json as a static snapshot. The Swagger UI at /docs/api will continue to work since it reads from this file at runtime. The spec can be manually updated when models change, and swapped for the official plugin when it ships.

2.2 Zod Plugin (NOT A BLOCKER)

Current config in schema.zmodel:17-20:

plugin zod {
    provider = '@core/zod'
    version = 'v4'
}

The Zod schema generation plugin is planned but not yet available in V3. However, this is not a blocker — the generated Zod schemas are not actually imported or used anywhere in the codebase. All Zod usage is hand-written schemas imported directly from zod/v4 for form validation and API input parsing. This plugin declaration can simply be removed during migration.

2.3 Access Control Plugin (NEW — Required in V3)

V3 requires an explicit plugin declaration for access control:

plugin policy {
    provider = '@zenstackhq/plugin-policy'
}

Must be added to schema.zmodel and @zenstackhq/plugin-policy installed.

2.4 TanStack Query Plugin (Changed)

Still exists but generates a different output pattern (client-based instead of standalone hooks). The plugin declaration in the schema may also change.

2.5 V3 Built-in Plugins

Only 3 built-in plugins in V3:

Plugin	Provider	Purpose
TypeScript	@core/typescript	Generates schema.ts, models.ts, input.ts
Prisma	@core/prisma	Generates Prisma schema (optional, for migration tooling)
Policy	@zenstackhq/plugin-policy	Access control enforcement

---

3. Package Changes

Remove

Package	Current Version
zenstack	~2.22.2
@zenstackhq/runtime	~2.22.2
@zenstackhq/openapi	~2.22.2
@prisma/client	dependency
prisma	dev dependency (can optionally keep via @core/prisma plugin)

Install

Package	Purpose
@zenstackhq/cli (devDep)	Replaces zenstack CLI (zen command)
@zenstackhq/orm	Replaces @zenstackhq/runtime + @prisma/client
@zenstackhq/plugin-policy	Access control (now a separate plugin)
pg + @types/pg	PostgreSQL driver (direct dependency)
zod	Peer dependency (bring-your-own, ^3.25.0 || ^4.0.0)

Update (same name, different API)

Package	Change
@zenstackhq/server	getPrisma → getClient, explicit schema
@zenstackhq/tanstack-query	Client-based hook pattern

---

4. CLI Command Changes

V2 Command	V3 Command
zenstack generate	zen generate
prisma db push	zen db push
prisma migrate dev	zen migrate dev
prisma migrate deploy	zen migrate deploy
prisma migrate status	zen migrate status

New V3 commands: zen check, zen format, zen init, zen info, zen generate --watch

Current package.json script:

"generate": "NODE_OPTIONS='--max-old-space-size=10140' zenstack generate && prisma db push"

V3 equivalent:

"generate": "NODE_OPTIONS='--max-old-space-size=10140' zen generate && zen db push"

---

5. Schema Changes Required

5.1 Default Location Change

• V2: schema.zmodel (project root)
• V3: zenstack/schema.zmodel (configurable via package.json "zenstack" key)

5.2 No abstract model or extends Usage — No Impact

Verified: 0 occurrences. No migration needed for the abstract model → type / extends → with change.

5.3 No @encrypted Usage — No Impact

Verified: 0 occurrences.

5.4 No .check() API Usage — No Impact

Verified: 0 occurrences. The removed check() API is not used.

---

6. New Features Available in V3

Opportunities (not migration requirements):

• Field-level access control (v3.2.0+): @allow('read', auth().id == id) on individual fields
• Custom procedures: proc keyword for business logic in the schema
• Computed fields: @computed for database-calculated fields
• Strongly typed JSON: Structured JSON field types in schema
• Kysely query builder: Direct SQL-level queries via $qb
• Expression blending: $expr clause for mixing CRUD with query builder
• exists API (v3.2.0+): await db.post.exists({ where: { ... } })
• between filter (v3.3.0+): Range queries
• Optimistic updates: Built into TanStack Query hooks
• @updatedAt(ignore: [...]) field exclusion (v3.3.0+)
• Smaller footprint: ~33 MB vs Prisma's ~224 MB
• No native binaries: Pure TypeScript, no Rust/WASM

---

7. Prerequisites

• Node.js: v20+
• TypeScript: v5.8.0+
• VSCode Extension: ZenStack V3 extension (different from V2; uses zmodel-v3 language ID)

---

8. Risk Assessment

Mitigated (No Longer Blocking)

#	Item	Mitigation
1	OpenAPI plugin unavailable	Freeze current zenstack-openapi.json as static snapshot; update manually when models change

High Risk

#	Item	Scope
3	Prisma Client Extensions → Runtime Plugins	Rewrite of lib/prisma.ts (~887 lines): ES sync, audit logging, auto-complete
4	@prisma/client type imports	~388 occurrences across ~379 files (automatable)
5	TanStack Query hook pattern change	93 generated hooks + hundreds of component usages

Medium Risk

#	Item	Scope
6	Multi-tenant client management	lib/multiTenantPrisma.ts rewrite
7	API handler route	app/api/model/[...path]/route.ts (~400 lines) with auto-user-injection
8	@password removal	Manual password hashing in app code
9	@omit removal	Move to ClientOptions.omit config (4 fields)
10	update/delete policy rejection behavior	Error handling may need adjustment

Low Risk

#	Item	Scope
11	future() → before() policy	1 occurrence, straightforward
12	CLI command changes	Script updates in package.json
13	Schema location	Configurable, can keep current
14	delegate kind usage	2 occurrences in SyncService.ts

---

9. Recommended Migration Strategy

Phase 0: Pre-Migration Setup

• Freeze current zenstack-openapi.json as a static snapshot (commit it as a checked-in artifact)
• Remove the plugin openapi and plugin zod declarations from schema.zmodel (neither will work in V3)
• Verify the Swagger UI at /docs/api still works with the static snapshot

Phase 1: Preparation (Can Start Now)

• Catalog all @prisma/client type imports and which specific types are used
• Document all $extends() behavior in lib/prisma.ts with test coverage
• Build a codemod script for type import migration
• Add password hashing to application code alongside @password (dual-path)

Phase 2: Schema & Plugins

• Add plugin policy { provider = '@zenstackhq/plugin-policy' } to schema
• Update future() → before() with 'post-update' policy type
• Remove @password and @omit attributes
• Update/remove OpenAPI and Zod plugin declarations

Phase 3: Core Runtime

• Replace PrismaClient with ZenStackClient + PostgresDialect
• Rewrite lib/prisma.ts: convert $extends() to V3 runtime plugins
• Update lib/multiTenantPrisma.ts for new client management
• Update all enhance() calls → $use(PolicyPlugin).$setAuth(user)
• Configure omit option in client constructor for sensitive fields

Phase 4: API Layer

• Update app/api/model/[...path]/route.ts for new handler API
• Port auto-user-injection logic to V3 patterns
• Run type import codemod across codebase

Phase 5: Frontend

• Update TanStack Query plugin configuration
• Add QuerySettingsProvider to app providers
• Update all component hook imports to client-based pattern
• Test all data-fetching flows

Phase 6: Validation

• Run full unit test suite
• E2E test all critical flows
• Verify Elasticsearch sync with runtime plugins
• Verify audit logging with runtime plugins
• Verify multi-tenant mode
• Performance comparison (V2 vs V3)

---

Sources

• ZenStack V3 Repository
• ZenStack V3 Releases
• Migrating From ZenStack V2
• Migrating From Prisma
• The Next Chapter Part I: Overview
• The Next Chapter Part II: An Extensible ORM
• The Next Chapter Part III: New Plugin System
• ZenStack V3 Landing Page
• ZenStack CLI Reference