TML-2852: enums become first-class in application code — typed I/O, db.enums, declaration-order ORDER BY (#769)

## At a glance

In the demo's own contract, `Post` carries a `Priority` enum — and the
column is typed as its value union everywhere you touch it:

```ts
const Priority = enumType('Priority', pgText,
  member('Low', 'low'), member('High', 'high'), member('Urgent', 'urgent'));   // declaration order ≠ lexical

// on a real model:  Post { …, priority: field.namedType(Priority) }

// READ — priority is 'low' | 'high' | 'urgent' (not string), sorted by DECLARATION order
getPostsByPriority()   // → rows ordered low, low, high, urgent  (not lexical)

// WRITE — only member values compile; 'nope' is a compile error, and the CHECK constraint rejects it at the DB

// INTROSPECT at runtime
db.enums.public.Priority.values        // ['low', 'high', 'urgent']  (ordered, literal-typed)
db.enums.public.Priority.members.High  // 'high'
```

This runs end-to-end against PGlite in `examples/prisma-next-demo` —
typed read, `db.enums.<ns>`, declaration-order `ORDER BY`, and the
slice-2 `CHECK` rejecting out-of-union writes.

## What this decides

An enum becomes a **first-class application concept**: its value union
flows into the static read/write types of **both** query lanes,
`db.enums.<ns>.<Name>` exposes it at runtime, and `ORDER BY` on an enum
column sorts by **declaration order**. It works for **text and
int-backed** enums and in **both authoring forms** (definition *and*
factory `defineContract`). Built on the merged substrate (slice 1) and
check-constraint enforcement (slice 2), and lands **additively** — PSL
`enum` stays native until the cutover, so only `enumType`-authored
contracts exercise it.

## How it builds up

1. **Typed I/O (R4/R5)** — narrow the codec type by the field's
`valueSet` to the value union, on **both paths**: the authored
`Definition` (no-emit) and the **emitted `contract.d.ts`** — the emitter
resolves a field's `valueSet` ref to the enum's member-value union,
codec-agnostically (text and int). Both lanes inherit it through the
field-output typemap; **non-enum fields are unchanged**.
2. **`db.enums.<ns>.<Name>` (R6)** — a runtime, literal-typed accessor
(`.values` / `.members.X` / `.has` / `.nameOf` / `.ordinalOf`) built
from that namespace's domain enums. Enums are **lane-agnostic contract
metadata**, so `db.enums` lives on the **`db` facade** alongside
`transaction` / `prepare` / `raw` / `context` (decided with the query
team) — a namespace-keyed map projected per target exactly like `db.sql`
/ `db.orm`. It matches the IR (`domain.namespaces[ns].enum`) and lets
the same enum name in two namespaces resolve independently.
Unbound-namespace targets (sqlite/mongo) get `db.enums.<Name>` via the
existing per-facade projection. Because enums sit on the facade rather
than adjacent to models, no reserved-name guard is needed — a model
named `enums` no longer collides.
3. **Declaration-order `ORDER BY` (R8, Postgres)** — renders
`array_position(ARRAY[…]::text[], col)` over the value-set's ordered
values.
4. **Factory-form authoring** — the new enum is authorable in the demo's
*real* factory-form contract (a top-level `enums` key threaded through
the factory overload, mirroring the definition form), not only the
definition form.

## Scope

**Additive / dark.** PSL `enum` keeps lowering to native (the repoint is
the cutover, TML-2853); member defaults are TML-2855; non-Postgres
`ORDER BY` (MySQL `FIELD(...)` / SQLite `CASE`) is future. Existing
fixtures are byte-identical apart from the demo.

## CI note

The repo-wide `pnpm typecheck` is red on **inherited `Cannot find
module` subpath errors** (`/contract-builder`, `/migration`, `/adapter`,
`/aggregate`, `/constants`) that reproduce on clean `origin/main` — a
separate main-health issue, not introduced here.

## Alternatives considered

- **Narrow from the emitted contract JSON** rather than the authored
`Definition` — rejected: emission widens the value-set to `string[]`,
erasing the literals.
- **A bespoke "enum codec"** — rejected: every field already carries a
codec; the enum is a `valueSet` restriction layered on top.
- **A dedicated `orderByDeclarationOrder()` API** — rejected: ordering
an enum column by declaration order should just work; the renderer
handles it implicitly.

🤖 Generated with [Claude Code](https://claude.com/claude-code)


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

## Release Notes

* **New Features**
* Added enum type definitions with first-class support for enum-backed
model fields in SQL contracts.
* Enum fields now narrow to literal value unions (e.g., `'user' |
'admin'` instead of generic `string`) in both read and write operations,
with compile-time type checking.
* Exposed enum metadata and lookup utilities (values list, names, member
maps, membership/ordinal checks) on the client facade under
`db.enums.<namespace>.<EnumName>` (lane-agnostic namespace-keyed map).
* Enum-backed ORDER BY now respects enum declaration order rather than
lexical order.
  * Added support for both string and numeric enum values.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: Will Madden <madden@prisma.io>
Co-authored-by: Will Madden <madden@prisma.io>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: 3 people

examples/prisma-next-demo/prisma/contract.ts

@@ -1,5 +1,15 @@
 import pgvector from '@prisma-next/extension-pgvector/pack';
-import { defineContract, rel } from '@prisma-next/postgres/contract-builder';
+import { defineContract, enumType, member, rel } from '@prisma-next/postgres/contract-builder';
+
+const pgText = { codecId: 'pg/text@1', nativeType: 'text' } as const;
+
+const Priority = enumType(
+  'Priority',
+  pgText,
+  member('Low', 'low'),
+  member('High', 'high'),
+  member('Urgent', 'urgent'),
+);
 
 export const contract = defineContract(
   {
@@ -27,13 +37,15 @@ export const contract = defineContract(
         id: field.id.uuidv4(),
         title: field.text(),
         userId: field.uuid(),
+        priority: field.namedType(Priority),
         createdAt: field.temporal.createdAt(),
         updatedAt: field.temporal.updatedAt(),
         embedding: field.namedType(types.Embedding1536).optional(),
       },
     });
 
     return {
+      enums: { Priority },
       types,
       models: {
         User: User.relations({

examples/prisma-next-demo/src/prisma-no-emit/context.ts

@@ -1,43 +1,24 @@
-import postgresAdapter from '@prisma-next/adapter-postgres/runtime';
-import postgresDriver from '@prisma-next/driver-postgres/runtime';
 import pgvector from '@prisma-next/extension-pgvector/runtime';
-import { SqlContractSerializer } from '@prisma-next/family-sql/ir';
-import { sql as sqlBuilder } from '@prisma-next/sql-builder/runtime';
+import postgres from '@prisma-next/postgres/runtime';
 import { orm } from '@prisma-next/sql-orm-client';
 import type { Runtime } from '@prisma-next/sql-runtime';
-import { createExecutionContext, createSqlExecutionStack } from '@prisma-next/sql-runtime';
-import postgresTarget from '@prisma-next/target-postgres/runtime';
 import { contract } from '../../prisma/contract';
 import { PostCollection, UserCollection } from '../orm-client/collections';
 
-export const stack = createSqlExecutionStack({
-  target: postgresTarget,
-  adapter: postgresAdapter,
-  driver: postgresDriver,
-  extensionPacks: [pgvector],
-});
+// No-emit flow: hand the TypeScript-authored contract straight to the
+// `postgres()` facade with deferred binding (no url at construction). The
+// facade owns stack/context/sql/enums, so the demo no longer hand-wires them.
+export const db = postgres<typeof contract>({ contract, extensions: [pgvector] });
 
-// The no-emit path passes the TS-authored contract directly; the
-// deserializer's method-level type parameter recovers the literal-
-// typed contract shape (from the generated `contract.d.ts`) so
-// downstream DSL calls keep their precise types.
-const validatedContract = new SqlContractSerializer().deserializeContract<typeof contract>(
-  contract,
-);
-
-export const context = createExecutionContext({
-  contract: validatedContract,
-  stack,
-});
-
-export const sql = sqlBuilder<typeof contract>({
-  context,
-  rawCodecInferer: { inferCodec: () => 'pg/text' },
-}).public;
+export const context = db.context;
+export const stack = db.stack;
+export const enums = db.enums;
+export const sql = db.sql.public;
 
 export function createOrmClient(runtime: Runtime) {
-  // The no-emit contract types its domain namespaces loosely, so narrow the
-  // `public` facet with a runtime guard rather than a cast.
+  // The demo builds runtimes externally (custom pool/middleware) and passes
+  // them in, so the ORM client is built against that runtime via the `orm()`
+  // builder rather than the facade's own lazily-bound `db.orm`.
   const client = orm({
     runtime,
     context,

examples/prisma-next-demo/src/prisma-no-emit/priority-feed.ts

@@ -0,0 +1,30 @@
+import type { Runtime } from '@prisma-next/sql-runtime';
+import { enums, sql } from './context';
+
+/**
+ * Reads posts ordered by their `Priority` enum column. The enum's declaration
+ * order (low -> high -> urgent) drives the sort, not lexical order, so the feed
+ * surfaces the lowest-priority posts first.
+ */
+export async function getPostsByPriority(runtime: Runtime) {
+  const rows = await runtime.execute(
+    sql.post.select('id', 'title', 'priority').orderBy('priority').orderBy('id').build(),
+  );
+  return rows;
+}
+
+/**
+ * Returns the declaration-ordered runtime surface for the `Priority` enum via
+ * the `db.enums` facade member (`enums.public.Priority`), demonstrating that
+ * the value tuple and helpers are reachable as lane-agnostic contract metadata.
+ */
+export function getPriorityEnum() {
+  // The no-emit contract types its domain namespaces loosely (index
+  // signature), so `enums['public']` is reached with bracket access and a
+  // runtime guard rather than a cast — the same shape `createOrmClient` uses.
+  const publicEnums = enums['public'];
+  if (publicEnums === undefined) {
+    throw new Error("Contract is missing the 'public' namespace enums");
+  }
+  return publicEnums.Priority;
+}

examples/prisma-next-demo/test/enum-surface.integration.test.ts

@@ -0,0 +1,151 @@
+import { instantiateExecutionStack } from '@prisma-next/framework-components/execution';
+import { createRuntime, type Runtime } from '@prisma-next/sql-runtime';
+import { timeouts, withDevDatabase } from '@prisma-next/test-utils';
+import { Pool } from 'pg';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { contract } from '../prisma/contract';
+import { context, sql, stack } from '../src/prisma-no-emit/context';
+import { getPostsByPriority, getPriorityEnum } from '../src/prisma-no-emit/priority-feed';
+import { initTestDatabase } from './utils/control-client';
+
+const authorId = '00000000-0000-0000-0000-000000000001';
+
+// Posts whose `Priority` enum values are deliberately out of declaration order
+// so the ORDER BY assertion below is meaningful. Post ids are uuids so the
+// secondary sort key is stable.
+const seed = [
+  {
+    id: '10000000-0000-0000-0000-00000000000a',
+    title: 'Ship it',
+    userId: authorId,
+    priority: 'high',
+  },
+  {
+    id: '10000000-0000-0000-0000-00000000000b',
+    title: 'Sketch',
+    userId: authorId,
+    priority: 'low',
+  },
+  {
+    id: '10000000-0000-0000-0000-00000000000c',
+    title: 'Polish',
+    userId: authorId,
+    priority: 'urgent',
+  },
+  { id: '10000000-0000-0000-0000-00000000000d', title: 'Draft', userId: authorId, priority: 'low' },
+] as const;
+
+async function openRuntime(
+  connectionString: string,
+): Promise<{ runtime: Runtime; close: () => Promise<void> }> {
+  const pool = new Pool({ connectionString });
+  const stackInstance = instantiateExecutionStack(stack);
+  const driver = stackInstance.driver;
+  if (!driver) {
+    throw new Error('Driver descriptor missing from execution stack');
+  }
+  try {
+    await driver.connect({ kind: 'pgPool', pool });
+  } catch (error) {
+    await pool.end();
+    throw error;
+  }
+  const runtime = createRuntime({ stackInstance, context, driver });
+  return { runtime, close: () => pool.end() };
+}
+
+describe('TS-authored enum on the demo contract (Post.priority)', () => {
+  it(
+    'db.enums exposes the declaration-ordered runtime surface',
+    async () => {
+      await withDevDatabase(async ({ connectionString }) => {
+        await initTestDatabase({ connection: connectionString, contract });
+        const { close } = await openRuntime(connectionString);
+        try {
+          const priority = getPriorityEnum();
+          expect(priority.values).toEqual(['low', 'high', 'urgent']);
+          expect(priority.names).toEqual(['Low', 'High', 'Urgent']);
+          expect(priority.members.Urgent).toBe('urgent');
+          expect(priority.has('high')).toBe(true);
+          const notAMember = 'nope' as 'low' | 'high' | 'urgent';
+          expect(priority.has(notAMember)).toBe(false);
+          expect(priority.ordinalOf('urgent')).toBe(2);
+        } finally {
+          await close();
+        }
+      }, {});
+    },
+    timeouts.spinUpPpgDev,
+  );
+
+  it(
+    'reading Post.priority narrows to the value union and sorts by declaration order',
+    async () => {
+      await withDevDatabase(async ({ connectionString }) => {
+        await initTestDatabase({ connection: connectionString, contract });
+        const { runtime, close } = await openRuntime(connectionString);
+        try {
+          await runtime.execute(
+            sql.user.insert([{ id: authorId, email: 'author@example.com', kind: 'user' }]).build(),
+          );
+          await runtime.execute(sql.post.insert([...seed]).build());
+
+          const ordered = await getPostsByPriority(runtime);
+
+          // The read narrows to the enum's own value union, not string. The
+          // expected type is taken from the `db.enums` surface rather than
+          // re-typed by hand, and asserted against the inferred row type with
+          // no annotation — so a widening to `string` fails here.
+          type PriorityValue = ReturnType<typeof getPriorityEnum>['values'][number];
+          const priorities = ordered.map((row) => row.priority);
+          expectTypeOf(priorities).toEqualTypeOf<PriorityValue[]>();
+
+          // Declaration order is low -> high -> urgent; lexical would be
+          // high, low, low, urgent.
+          expect(priorities).toEqual(['low', 'low', 'high', 'urgent']);
+          expect(ordered.map((row) => row.id)).toEqual([
+            '10000000-0000-0000-0000-00000000000b',
+            '10000000-0000-0000-0000-00000000000d',
+            '10000000-0000-0000-0000-00000000000a',
+            '10000000-0000-0000-0000-00000000000c',
+          ]);
+        } finally {
+          await close();
+        }
+      }, {});
+    },
+    timeouts.spinUpPpgDev,
+  );
+
+  it(
+    'the enum CHECK constraint rejects out-of-union values written at runtime',
+    async () => {
+      await withDevDatabase(async ({ connectionString }) => {
+        await initTestDatabase({ connection: connectionString, contract });
+        const { runtime, close } = await openRuntime(connectionString);
+        try {
+          await runtime.execute(
+            sql.user.insert([{ id: authorId, email: 'author@example.com', kind: 'user' }]).build(),
+          );
+          await expect(
+            runtime.execute(
+              sql.post
+                .insert([
+                  {
+                    id: '10000000-0000-0000-0000-0000000000ff',
+                    title: 'Bad',
+                    userId: authorId,
+                    priority: 'nope' as 'low',
+                  },
+                ])
+                .build(),
+            ),
+          ).rejects.toThrow();
+        } finally {
+          await close();
+        }
+      }, {});
+    },
+    timeouts.spinUpPpgDev,
+  );
+});

examples/prisma-next-demo/test/enum-surface.types.test-d.ts

@@ -0,0 +1,29 @@
+import type { ResultType } from '@prisma-next/framework-components/runtime';
+import { expectTypeOf, test } from 'vitest';
+import { type enums, sql } from '../src/prisma-no-emit/context';
+
+type Priority = 'low' | 'high' | 'urgent';
+
+test('reading Post.priority yields the value union, not string', () => {
+  const plan = sql.post.select('id', 'priority').build();
+  type Row = ResultType<typeof plan>;
+  // The non-enum id stays the codec output (string), unaffected by narrowing.
+  expectTypeOf<Row['id']>().toEqualTypeOf<string>();
+  // The non-null enum column narrows to its value union — no spurious `| null`.
+  expectTypeOf<Row['priority']>().toEqualTypeOf<Priority>();
+  expectTypeOf<Row['priority']>().not.toEqualTypeOf<string>();
+});
+
+test('writing Post.priority only accepts the value union', () => {
+  sql.post.insert([{ id: 'a', title: 'ok', userId: 'u', priority: 'high' }]).build();
+
+  sql.post.insert([
+    // @ts-expect-error 'nope' is not a Priority member value.
+    { id: 'b', title: 'bad', userId: 'u', priority: 'nope' },
+  ]);
+});
+
+test('db.enums value tuple keeps its literal declaration order', () => {
+  type Values = (typeof enums)['public']['Priority']['values'];
+  expectTypeOf<Values>().toEqualTypeOf<readonly ['low', 'high', 'urgent']>();
+});

packages/1-framework/0-foundation/contract/package.json

@@ -44,6 +44,7 @@
     "./apply-specifier-default-control-policy": "./dist/apply-specifier-default-control-policy.mjs",
     "./contract-validation-error": "./dist/contract-validation-error.mjs",
     "./default-namespace": "./dist/default-namespace.mjs",
+    "./enum-accessor": "./dist/enum-accessor.mjs",
     "./hashing": "./dist/hashing.mjs",
     "./hashing-utils": "./dist/hashing-utils.mjs",
     "./resolve-domain-model": "./dist/resolve-domain-model.mjs",

packages/1-framework/0-foundation/contract/src/domain-types.ts

@@ -1,4 +1,5 @@
 import type { CrossReference } from './cross-reference';
+import type { JsonValue } from './types';
 import type { ValueSetRef } from './value-set-ref';
 
 export type ScalarFieldType = {
@@ -34,7 +35,7 @@ export type ContractField = {
  */
 export type ContractEnum = {
   readonly codecId: string;
-  readonly members: readonly { readonly name: string; readonly value: string }[];
+  readonly members: readonly { readonly name: string; readonly value: JsonValue }[];
 };
 
 export type ContractRelationOn = {