TML-2955: A client-safe static surface — @prisma-next/<target>/static (#888)

## At a glance

You can now use a contract's enums, query builder, and generated types
in a `'use client'` component — with **no database driver in the browser
bundle**:

```tsx
'use client';
import mongoStatic from '@prisma-next/mongo/static';
import contractJson from './contract.json' with { type: 'json' };
import type { Contract } from './contract';

const { enums } = mongoStatic<Contract>({ contractJson });

export function OrderTypePicker() {
  // fully typed from the contract — enums.OrderType.members.Delivery, .Pickup, …
  return <RadioGroup options={Object.values(enums.OrderType.members)} />;
}
```

The same call shape exists on every target (`postgresStatic`,
`sqliteStatic`), and the same object is exposed on a connected client as
`db.context` / `db.contract`.

## The decision

**Expose the `ExecutionContext` as a first-class, client-safe surface —
a new `@prisma-next/<target>/static` entrypoint — symmetrically on all
three target facades.**

The `ExecutionContext` is the driver-free core every query is built
against: the contract, its codecs, the query operations, and the derived
types. Enums, the query builder, and `raw` are all just views over it.
It needs no connection and no driver to construct — so in principle it's
usable anywhere, including the browser. This PR makes that real and
uniform.

## Why it wasn't already usable

The context existed but you couldn't get at it cleanly from client code:

- **Postgres** built it upfront and exposed it as `db.context` — but
only on a fully-wired, driver-carrying client.
- **Mongo** built the equivalent lazily *inside the connect path*, never
exposed it, and typed its contract as `unknown`.
- There was **no driver-free entrypoint** on any target, so importing
the facade to reach enums also imported the DB driver.

So when an app needed typed enums in a `'use client'` form, it fell back
to an interim: hand-calling the low-level `buildNamespacedEnums(...)`
and casting the untyped result in application code. That worked but was
a narrow, per-consumer workaround, not the abstraction.

## What this PR does

- Adds **`@prisma-next/<target>/static`** with `<target>Static({
contractJson })`, returning the `ExecutionContext` plus the surface
derived from it (`enums`, query builder, `raw`, `contract`). It's
driver-free by construction, and a test walks the entrypoint's import
graph to keep it that way.
- Builds the Mongo context **upfront**, types it
`MongoExecutionContext<TContract>`, and exposes `db.context` /
`db.contract` — matching Postgres, so the shape is the same across
targets.
- Routes each facade *and* its `/static` twin through **one shared
builder**, so the enum typing lives in framework code once instead of a
cast in every app.
- Migrates `examples/retail-store` off the interim: `src/enums.ts` now
derives from `mongoStatic(...)`, consumed by the `'use client'` checkout
form — which doubles as the `next build` "no driver in the client
bundle" acceptance test.

## One cross-cutting change worth a look

Making the static context truly driver-free reached one layer deeper
than the facades. Building the context aggregates the target's codecs,
and the Mongo codec imported `ObjectId` from `mongodb` (a value import),
which drags the whole driver into a client bundle. `ObjectId` is really
a `bson` class that `mongodb` re-exports, so the codec now imports it
from the standalone `bson` package. It's a one-line change but it lives
in `packages/3-mongo-target/2-mongo-adapter`, and it's what lets `next
build` succeed with zero driver code client-side.

Extension packs (postgis, pgvector, …) are unaffected: the *facade*
still builds its context from the full stack including
`options.extensions`; only the client-safe `/static` path is
target+adapter-only.

## Testing

Full local gate green (build, typecheck, lint incl.
`lint:deps`/`lint:casts`, `check:upgrade-coverage`, `fixtures:check`,
`test:packages`/`integration`/`e2e`) and CI green. `retail-store` `next
build` produces no `mongodb` in the client bundle. Upgrade instructions
recorded as additive/incidental for 0.14→0.15.

## Alternatives considered

- **Keep the app-code interim** (`buildNamespacedEnums` + a cast).
Rejected: untyped without a per-call cast, duplicated per consumer, and
it leaks a framework detail into every app.
- **An enums-only helper** — the `mongoEnums` /
`@prisma-next/mongo/enums` point-solution prototyped in #880 and pulled
back out. Rejected: it solved one symptom (enums) rather than exposing
the abstraction they derive from. Exposing the whole `ExecutionContext`
gives enums, query building, `raw`, and types from one surface,
symmetrically.
- **Make the existing `/runtime` entrypoint tree-shakeable** instead of
adding `/static`. Rejected: the driver is imported at module scope, so
bundlers can't reliably drop it. A separate driver-free module is a hard
boundary — and the client-safety test enforces it.

Spec:
[`projects/expose-static-execution-context/spec.md`](projects/expose-static-execution-context/spec.md).
Closes TML-2955.

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


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

* **New Features**
* Added contract “static” entrypoints for Mongo, Postgres, and SQLite
(e.g., `/<target>Static({ contractJson })`) that expose `context`,
`contract`, enums, query/`raw`, and related helpers.
  * Added `./static` subpath exports for Mongo/Postgres/SQLite.
  * Mongo facade now exposes `db.context` and `db.contract`.

* **Bug Fixes**
* Improved type preservation for `contract` (prevents widening to
`unknown`) and aligned runtime/static surfaces.
  * Strengthened validation and errors for required extension packs.

* **Documentation**
  * Updated 0.14 → 0.15 upgrade notes for the new static APIs.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: willbot <w.a.madden+machine@gmail.com>
Signed-off-by: Will Madden <madden@prisma.io>

Author: wmadden-electric

examples/retail-store/src/enums.ts

@@ -1,11 +1,5 @@
-import { buildNamespacedEnums, type NamespacedEnums } from '@prisma-next/contract/enum-accessor';
-import { blindCast } from '@prisma-next/utils/casts';
+import mongoStatic from '@prisma-next/mongo/static';
 import type { Contract } from './contract';
 import contractJson from './contract.json' with { type: 'json' };
-// Interim: build the enum accessors from the static contract with a blindCast.
-// TML-2955 will expose @prisma-next/mongo/static so the typing comes from the
-// framework and this whole module can be deleted.
-export const enums = blindCast<
-  NamespacedEnums<Contract>['__unbound__'],
-  'buildNamespacedEnums returns untyped EnumAccessor; cast to the typed shape from Contract'
->(buildNamespacedEnums(contractJson.domain)['__unbound__']);
+
+export const enums = mongoStatic<Contract>({ contractJson }).enums;

packages/1-framework/0-foundation/contract/src/enum-accessor.ts

@@ -1,3 +1,4 @@
+import { blindCast } from '@prisma-next/utils/casts';
 import type { Contract } from './contract-types';
 import type { ContractEnum } from './domain-types';
 import type { JsonValue } from './types';
@@ -63,16 +64,17 @@ export function buildEnumsMapForNamespace(
   return result;
 }
 
-export function buildNamespacedEnums(domain: {
-  readonly namespaces: Readonly<
-    Record<string, { readonly enum?: Readonly<Record<string, ContractEnum>> }>
-  >;
-}): Record<string, Record<string, EnumAccessor>> {
+export function buildNamespacedEnums<TContract extends Contract>(
+  domain: TContract['domain'],
+): NamespacedEnums<TContract> {
   const result: Record<string, Record<string, EnumAccessor>> = {};
   for (const namespaceId of Object.keys(domain.namespaces)) {
     result[namespaceId] = buildEnumsMapForNamespace(domain, namespaceId);
   }
-  return result;
+  return blindCast<
+    NamespacedEnums<TContract>,
+    'built dynamically from domain.namespaces; the mapped-type shape cannot be proven statically'
+  >(result);
 }
 
 type Present<T> = Exclude<T, undefined>;

packages/1-framework/0-foundation/contract/test/enum-accessor.test.ts

@@ -1,11 +1,14 @@
 import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { Contract } from '../src/contract-types';
 import type { ContractEnumAccessor, EnumMemberNames, EnumValues } from '../src/enum-accessor';
 import {
   buildEnumsMapForNamespace,
   buildNamespacedEnums,
   createEnumAccessor,
 } from '../src/enum-accessor';
 
+type ContractWithDomain<TDomain> = Contract & { readonly domain: TDomain };
+
 const roleEnum = {
   codecId: 'pg/text@1',
   members: [
@@ -187,11 +190,11 @@ describe('buildNamespacedEnums()', () => {
   it('keys the accessor map by namespace then enum name', () => {
     const domain = {
       namespaces: {
-        public: { enum: { Role: roleEnum, Status: statusEnum } },
+        public: { models: {}, enum: { Role: roleEnum, Status: statusEnum } },
       },
     };
 
-    const enums = buildNamespacedEnums(domain);
+    const enums = buildNamespacedEnums<ContractWithDomain<typeof domain>>(domain);
     expect(Object.keys(enums).sort()).toEqual(['public']);
     expect(enums['public']?.['Role']?.values).toEqual(['user', 'admin']);
     expect(enums['public']?.['Status']?.values).toEqual(['active', 'inactive', 'pending']);
@@ -200,22 +203,23 @@ describe('buildNamespacedEnums()', () => {
   it('resolves same-named enums in different namespaces independently', () => {
     const domain = {
       namespaces: {
-        public: { enum: { Role: roleEnum } },
-        audit: { enum: { Role: statusEnum } },
+        public: { models: {}, enum: { Role: roleEnum } },
+        audit: { models: {}, enum: { Role: statusEnum } },
       },
     };
 
-    const enums = buildNamespacedEnums(domain);
+    const enums = buildNamespacedEnums<ContractWithDomain<typeof domain>>(domain);
     expect(enums['public']?.['Role']?.values).toEqual(['user', 'admin']);
     expect(enums['audit']?.['Role']?.values).toEqual(['active', 'inactive', 'pending']);
   });
 
   it('exposes member accessors and helpers per namespace', () => {
     const domain = {
-      namespaces: { public: { enum: { Role: roleEnum } } },
+      namespaces: { public: { models: {}, enum: { Role: roleEnum } } },
     };
 
-    const role = buildNamespacedEnums(domain)['public']?.['Role'];
+    const role =
+      buildNamespacedEnums<ContractWithDomain<typeof domain>>(domain)['public']?.['Role'];
     expect(role?.members['User']).toBe('user');
     expect(role?.has('admin')).toBe(true);
     expect(role?.nameOf('user')).toBe('User');
@@ -224,10 +228,12 @@ describe('buildNamespacedEnums()', () => {
 
   it('yields an empty enum map for a namespace without enums', () => {
     const domain = {
-      namespaces: { public: {} },
+      namespaces: { public: { models: {} } },
     };
 
-    expect(buildNamespacedEnums(domain)).toEqual({ public: {} });
+    expect(buildNamespacedEnums<ContractWithDomain<typeof domain>>(domain)).toEqual({
+      public: {},
+    });
   });
 });
 

packages/2-mongo-family/7-runtime/src/mongo-execution-stack.ts

@@ -111,16 +111,19 @@ export interface MongoCodecLookup {
  *
  * Mirrors SQL's `ExecutionContext` in role; Mongo's flavour is leaner because there are no parameterised codecs, JSON-schema validators, or mutation-default generators in scope yet.
  */
-export interface MongoExecutionContext<TTargetId extends string = 'mongo'> {
-  readonly contract: unknown;
+export interface MongoExecutionContext<TContract = unknown, TTargetId extends string = 'mongo'> {
+  readonly contract: TContract;
   readonly codecs: MongoCodecLookup;
   readonly stack: MongoExecutionStack<TTargetId>;
 }
 
-export function createMongoExecutionContext<TTargetId extends string = 'mongo'>(options: {
-  readonly contract: unknown;
+export function createMongoExecutionContext<
+  TContract = unknown,
+  TTargetId extends string = 'mongo',
+>(options: {
+  readonly contract: TContract;
   readonly stack: MongoExecutionStack<TTargetId>;
-}): MongoExecutionContext<TTargetId> {
+}): MongoExecutionContext<TContract, TTargetId> {
   const registry = newMongoCodecRegistry();
   const owners = new Map<string, string>();
 

packages/2-mongo-family/7-runtime/test/mongo-execution-stack.test.ts

@@ -2,10 +2,11 @@ import mongoRuntimeAdapter from '@prisma-next/adapter-mongo/runtime';
 import { isRuntimeError } from '@prisma-next/framework-components/runtime';
 import { mongoCodec, newMongoCodecRegistry } from '@prisma-next/mongo-codec';
 import mongoRuntimeTarget from '@prisma-next/target-mongo/runtime';
-import { describe, expect, it } from 'vitest';
+import { describe, expect, expectTypeOf, it } from 'vitest';
 import {
   createMongoExecutionContext,
   createMongoExecutionStack,
+  type MongoExecutionContext,
   type MongoRuntimeExtensionDescriptor,
 } from '../src/mongo-execution-stack';
 
@@ -146,6 +147,17 @@ describe('createMongoExecutionContext', () => {
     expect(context.contract).toBe(contract);
     expect(context.stack).toBe(stack);
   });
+
+  it('preserves the TContract type on context.contract (no unknown widening)', () => {
+    const stack = createMongoExecutionStack({
+      target: mongoRuntimeTarget,
+      adapter: mongoRuntimeAdapter,
+    });
+    const contract = { target: 'mongo' as const, storageHash: 'sha256:test' };
+    const context = createMongoExecutionContext({ contract, stack });
+    expectTypeOf(context).toMatchTypeOf<MongoExecutionContext<typeof contract>>();
+    expectTypeOf(context.contract).toEqualTypeOf<typeof contract>();
+  });
 });
 
 describe('runtime adapter descriptor', () => {

packages/3-extensions/mongo/package.json

@@ -65,6 +65,7 @@
     "./control": "./dist/control.mjs",
     "./family": "./dist/family.mjs",
     "./runtime": "./dist/runtime.mjs",
+    "./static": "./dist/static.mjs",
     "./target": "./dist/target.mjs",
     "./package.json": "./package.json"
   },

packages/3-extensions/mongo/src/exports/static.ts

@@ -0,0 +1,2 @@
+export type { MongoStaticContext } from '../static/mongo-static';
+export { default } from '../static/mongo-static';

packages/3-extensions/mongo/src/runtime/mongo.ts

@@ -1,52 +1,38 @@
-import mongoRuntimeAdapter from '@prisma-next/adapter-mongo/runtime';
-import { buildNamespacedEnums, type NamespacedEnums } from '@prisma-next/contract/enum-accessor';
 import { MongoDriverImpl } from '@prisma-next/driver-mongo';
 import { MongoContractSerializer } from '@prisma-next/family-mongo/ir';
-import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
 import { AsyncIterableResult } from '@prisma-next/framework-components/runtime';
 import type {
   AnyMongoTypeMaps,
   MongoContract,
   MongoContractWithTypeMaps,
 } from '@prisma-next/mongo-contract';
 import type { MongoOrmClient, MongoQueryPlan, MongoRawClient } from '@prisma-next/mongo-orm';
-import { mongoOrm, mongoRaw } from '@prisma-next/mongo-orm';
-import { mongoQuery } from '@prisma-next/mongo-query-builder';
+import { mongoOrm } from '@prisma-next/mongo-orm';
 import type { MongoMiddleware, MongoRuntime } from '@prisma-next/mongo-runtime';
-import {
-  createMongoExecutionContext,
-  createMongoExecutionStack,
-  createMongoRuntime,
-} from '@prisma-next/mongo-runtime';
-import mongoRuntimeTarget from '@prisma-next/target-mongo/runtime';
-import { blindCast } from '@prisma-next/utils/casts';
+import { createMongoRuntime, type MongoExecutionContext } from '@prisma-next/mongo-runtime';
 import { ifDefined } from '@prisma-next/utils/defined';
+import { buildMongoStaticContext, type MongoStaticContext } from '../static/mongo-static';
 import {
   type MongoBinding,
   type MongoBindingInput,
   resolveMongoBinding,
   resolveOptionalMongoBinding,
 } from './binding';
 
-export type MongoTargetId = typeof mongoRuntimeTarget.targetId;
+export type MongoTargetId = 'mongo';
 
 type UnboundEnums<TContract extends MongoContractWithTypeMaps<MongoContract, AnyMongoTypeMaps>> =
-  NamespacedEnums<TContract>[typeof UNBOUND_NAMESPACE_ID];
-
-function unboundNamespace<T>(builderOutput: { readonly [UNBOUND_NAMESPACE_ID]?: unknown }): T {
-  return blindCast<T, 'the unbound namespace always exists on a mongo builder output'>(
-    builderOutput[UNBOUND_NAMESPACE_ID],
-  );
-}
+  MongoStaticContext<TContract>['enums'];
 
 export interface MongoClient<
   TContract extends MongoContractWithTypeMaps<MongoContract, AnyMongoTypeMaps>,
 > {
   readonly orm: MongoOrmClient<TContract>;
-  readonly query: ReturnType<typeof mongoQuery<TContract>>;
+  readonly query: MongoStaticContext<TContract>['query'];
   readonly raw: MongoRawClient<TContract>;
   readonly contract: TContract;
   readonly enums: UnboundEnums<TContract>;
+  readonly context: MongoExecutionContext<TContract>;
   execute<Row>(plan: MongoQueryPlan<Row>): AsyncIterableResult<Row>;
   connect(bindingInput?: MongoBindingInput): Promise<MongoRuntime>;
   runtime(): Promise<MongoRuntime>;
@@ -133,9 +119,7 @@ export default function mongo<
   const contract = resolveContract(options);
   let binding = resolveOptionalMongoBinding(options);
 
-  // `mongoQuery` calls its parameter `contractJson`, but accepts the validated
-  // contract value here (it normalises both internally).
-  const query = mongoQuery<TContract>({ contractJson: contract });
+  const { context, query, enums, raw } = buildMongoStaticContext<TContract>(contract);
 
   // Single source of truth for the lifecycle. `runtimePromise` is the in-flight
   // or settled build; `closed` is the terminal state set by `close()`. A failed
@@ -145,11 +129,6 @@ export default function mongo<
   let ownedDispose: (() => Promise<void>) | undefined;
 
   const buildRuntime = async (resolvedBinding: MongoBinding): Promise<MongoRuntime> => {
-    const stack = createMongoExecutionStack({
-      target: mongoRuntimeTarget,
-      adapter: mongoRuntimeAdapter,
-    });
-    const context = createMongoExecutionContext({ contract, stack });
     const driver =
       resolvedBinding.kind === 'url'
         ? await MongoDriverImpl.fromConnection(resolvedBinding.url, resolvedBinding.dbName)
@@ -201,18 +180,13 @@ export default function mongo<
     executor: { execute },
   });
 
-  const raw = mongoRaw<TContract>({ contract });
-
-  const enums: UnboundEnums<TContract> = unboundNamespace(
-    Object.freeze(buildNamespacedEnums(contract.domain)),
-  );
-
   return {
     orm,
     query,
     raw,
     contract,
     enums,
+    context,
     execute,
 
     async connect(bindingInput?: MongoBindingInput): Promise<MongoRuntime> {

packages/3-extensions/mongo/src/static/mongo-static.ts

@@ -0,0 +1,65 @@
+import mongoRuntimeAdapter from '@prisma-next/adapter-mongo/runtime';
+import { buildNamespacedEnums, type NamespacedEnums } from '@prisma-next/contract/enum-accessor';
+import { MongoContractSerializer } from '@prisma-next/family-mongo/ir';
+import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
+import type {
+  AnyMongoTypeMaps,
+  MongoContract,
+  MongoContractWithTypeMaps,
+} from '@prisma-next/mongo-contract';
+import type { MongoRawClient } from '@prisma-next/mongo-orm';
+import { mongoRaw } from '@prisma-next/mongo-orm';
+import { mongoQuery } from '@prisma-next/mongo-query-builder';
+import {
+  createMongoExecutionContext,
+  createMongoExecutionStack,
+  type MongoExecutionContext,
+} from '@prisma-next/mongo-runtime';
+import mongoRuntimeTarget from '@prisma-next/target-mongo/runtime';
+import { assertDefined } from '@prisma-next/utils/assertions';
+import { blindCast } from '@prisma-next/utils/casts';
+
+type UnboundEnums<TContract extends MongoContractWithTypeMaps<MongoContract, AnyMongoTypeMaps>> =
+  NamespacedEnums<TContract>[typeof UNBOUND_NAMESPACE_ID];
+
+function extractUnboundEnums<
+  TContract extends MongoContractWithTypeMaps<MongoContract, AnyMongoTypeMaps>,
+>(contract: TContract): UnboundEnums<TContract> {
+  const enums = buildNamespacedEnums<TContract>(contract.domain)[UNBOUND_NAMESPACE_ID];
+  assertDefined(enums, 'the unbound namespace always exists on a mongo builder output');
+  return enums;
+}
+
+export interface MongoStaticContext<
+  TContract extends MongoContractWithTypeMaps<MongoContract, AnyMongoTypeMaps>,
+> {
+  readonly context: MongoExecutionContext<TContract>;
+  readonly contract: TContract;
+  readonly enums: UnboundEnums<TContract>;
+  readonly query: ReturnType<typeof mongoQuery<TContract>>;
+  readonly raw: MongoRawClient<TContract>;
+}
+
+export function buildMongoStaticContext<
+  TContract extends MongoContractWithTypeMaps<MongoContract, AnyMongoTypeMaps>,
+>(contract: TContract): MongoStaticContext<TContract> {
+  const stack = createMongoExecutionStack({
+    target: mongoRuntimeTarget,
+    adapter: mongoRuntimeAdapter,
+  });
+  const context = createMongoExecutionContext<TContract>({ contract, stack });
+  const enums = extractUnboundEnums(contract);
+  const query = mongoQuery<TContract>({ contractJson: contract });
+  const raw = mongoRaw<TContract>({ contract });
+  return { context, contract, enums, query, raw };
+}
+
+export default function mongoStatic<
+  TContract extends MongoContractWithTypeMaps<MongoContract, AnyMongoTypeMaps>,
+>(options: { readonly contractJson: unknown }): MongoStaticContext<TContract> {
+  const contract = blindCast<
+    TContract,
+    'MongoContractSerializer validates and returns a typed contract'
+  >(new MongoContractSerializer().deserializeContract(options.contractJson));
+  return buildMongoStaticContext(contract);
+}