## Linked issue

n/a — no ticket.

## At a glance

```ts
const Priority = enumType(
  'Priority',
  { codecId: 'pg/int4@1', nativeType: 'int4' },
  member('Low', 0),
  member('High', 1),
  member('Urgent', 2),
);
```

Ordering stays ordinary SQL: `ORDER BY "priority" ASC`. Numeric values
encode the priority ranking explicitly; text-backed enum values sort as
text rather than by declaration order.

## Summary

Enum metadata should not silently rewrite SQL ordering. Remove the
declaration-order rewrite, support numeric enum membership checks, and
use numeric priorities in the demo so its intended ranking follows its
stored values.

## Decision

1. Render `ORDER BY` and `DISTINCT ON` expressions normally, without
consulting enum value sets.
2. Accept finite numeric members when deriving CHECK constraints.
Scalars use unquoted numeric literals; numeric arrays compare both
operands as `numeric[]`. Existing string quoting and text-array checks
remain unchanged.
3. Represent demo priorities as `Low = 0`, `High = 1`, `Urgent = 2` in
both TypeScript and PSL.

## Notes for the reviewer

- PostgreSQL native enum types retain PostgreSQL's own declaration-order
semantics. The ordering renderer introduces no casts or replacement
policy.
- Most added lines are regenerated demo contract snapshots. The demo's
baseline fixture migration and subsequent snapshot links were
regenerated for numeric priorities; users with an existing demo database
need to reset it. This is not a data-conversion migration for deployed
databases.
- Non-finite numeric membership literals and unsupported encoded values
remain rejected.

## How it fits together

1. The SQL adapter removes enum-specific ordering and table-source
lookup helpers.
2. Contract authoring passes encoded string or numeric members to the
target CHECK renderer.
3. The PostgreSQL renderer preserves numeric comparison semantics for
scalar and array membership.
4. The demo updates declarations, default-value examples, raw SQL
writes, type tests, migration fixtures, and emitted contracts together.

## Behavior changes & evidence

- Ordinary text-value ordering and unchanged `DISTINCT ON` expressions
are covered by
[`order-by-enum.integration.test.ts`](packages/3-targets/6-adapters/postgres/test/migrations/order-by-enum.integration.test.ts).
- Numeric CHECK predicates are implemented in
[`check-expressions.ts`](packages/3-targets/3-targets/postgres/src/core/check-expressions.ts),
with [unit
tests](packages/3-targets/3-targets/postgres/test/check-expressions.test.ts)
and [live database
tests](packages/3-targets/3-targets/postgres/test/check-expressions.integration.test.ts)
across smallint, integer, real, double precision, and numeric storage.
- Numeric enum authoring and end-to-end priority behavior are covered by
the SQL TS/PSL authoring suites and
[`enum-surface.integration.test.ts`](examples/prisma-8-demo/test/enum-surface.integration.test.ts).

## Testing performed

- SQL TypeScript authoring: 489 passed.
- SQL PSL authoring: 437 passed.
- PostgreSQL target: 1,606 passed.
- PostgreSQL adapter: 867 passed, 3 expected failures, 1 skipped.
- Demo: 73 passed, including migration replay.
- Typechecks for the demo, SQL TS/PSL authoring, and PostgreSQL target:
passed.
- Full build: 85 tasks passed.
- `pnpm fixtures:check`, `pnpm lint:skills`, `pnpm
check:upgrade-coverage`, Biome, focused dependency lint, and diff
whitespace checks: passed.

## Skill update

Added `explicit-enum-sort-values` to the [app upgrade
instructions](skills/prisma-8/upgrading/app/upgrades/8.0.0-rc.8-to-8.0.0-rc.9/instructions.md),
covering explicit ranking, numeric enum declarations, and
data-preserving migration requirements for existing databases.

## Checklist

- [x] All commits are DCO signed off.
- [x] I read CONTRIBUTING.md; this change is scoped to enum ordering and
explicit numeric priorities.
- [x] Tests are updated.
- [ ] The PR title uses a Linear ticket prefix — not applicable; no
ticket.
- [x] The Skill update section is filled in.

## Alternatives considered

- Keep declaration-order emulation: rejected because enum metadata
should not override the requested SQL expression.
- Cast native PostgreSQL enums to text: not chosen because the requested
behavior is to leave `ORDER BY` unchanged, not impose another sorting
policy.
- Disable numeric membership checks: rejected because ordinary numeric
CHECK predicates can enforce the same membership guarantee as string
enums.


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

* **Behavior Changes**
* PostgreSQL text-backed enum columns now sort by stored text values
rather than declaration order.
* `ORDER BY` and `DISTINCT ON` queries retain straightforward column
expressions, including NULL handling.
* Numeric enum values are now supported for PostgreSQL-backed schemas
and membership constraints.
* Numeric enum defaults and generated type definitions are reflected
consistently in the Prisma 8 demo.

* **Documentation**
* Upgrade guidance explains how to preserve semantic ordering with
explicit numeric values or ranking expressions.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: Steven McClankerton <tatarintsev@prisma.io>
Co-authored-by: Steven McClankerton <tatarintsev@prisma.io>