feat(paradedb): adopt emptyContract() and drop placeholder contract.prisma

Wire migrations-only contract emit via emptyContract with the same postgres
target ref; document the pattern in ADR 212 and contract-space layout rule.

Signed-off-by: Will Madden <madden@prisma.io>

Author: wmadden

.agents/rules/contract-space-package-layout.mdc

@@ -24,7 +24,8 @@ applications) uses the **same** on-disk shape:
 │       ├── end-contract.d.ts
 │       └── migration.ts
 └── src/
-    ├── contract.prisma              ← PSL source (preferred; TS fallback noted below)
+    ├── contract.prisma              ← PSL source when the space has app-visible schema (preferred; exceptions below)
+    ├── contract.ts                  ← optional TS source (narrow exception)
     ├── contract.json                ← emitted (do not edit)
     ├── contract.d.ts                ← emitted (do not edit)
     └── exports/control.ts           ← descriptor; JSON-imports the artefacts
@@ -35,17 +36,23 @@ applications) uses the **same** on-disk shape:
 
 ## Rules (these are the spots where mistakes recur)
 
-- **Author contracts in PSL (`src/contract.prisma`)**, not TypeScript.
+- **Author contracts in PSL (`src/contract.prisma`)** when the space
+  contributes app-visible schema (models, storage types, namespaces).
   PSL is the canonical authoring surface — it reads as a schema (not as
   builder calls), interoperates with brownfield Prisma schemas, and
   keeps the contract decoupled from the workspace's TS type system.
   Wire it with
   `prismaContract('./src/contract.prisma', { output: 'src/contract.json', target })`.
-  The narrow exception is contracts that need to declare typed objects
-  the PSL surface doesn't yet express (e.g. parameterised
+  **Migrations-only spaces** that install invariants (e.g. a Postgres
+  extension) but ship no tables or native types omit the source file
+  and wire
+  `emptyContract({ output: 'src/contract.json', target })` in
+  `prisma-next.config.ts` (see `@prisma-next/extension-paradedb`).
+  The narrow **TypeScript** exception is contracts that need to declare
+  typed objects the PSL surface doesn't yet express (e.g. parameterised
   `storage.types` base-type registrations like pgvector's `vector` —
   `types {}` blocks instantiate, they don't register). Such packages
-  may use `src/contract.ts` + `typescriptContract(contract, 'src/contract.json')`,
+  use `src/contract.ts` + `typescriptContract(contract, 'src/contract.json')`,
   with a comment in the contract source naming the missing PSL surface.
 - **No `<space-id>` subdirectory inside `migrations/`.** A package owns
   exactly one contract space, so the `<space-id>` directory adds no

docs/architecture docs/adrs/ADR 212 - Contract spaces.md

@@ -103,7 +103,8 @@ Every package that exposes a contract space — published extensions (`packages/
 │       ├── end-contract.d.ts
 │       └── migration.ts             ← `Migration` subclass
 └── src/
-    ├── contract.prisma              ← PSL schema source (preferred — see below)
+    ├── contract.prisma              ← PSL schema source when the space has app-visible schema (preferred — see below)
+    ├── contract.ts                  ← optional TS source (narrow exception — see below)
     ├── contract.json                ← emitted (do not edit)
     ├── contract.d.ts                ← emitted (do not edit)
     └── exports/control.ts           ← descriptor; JSON-imports the artefacts
@@ -113,7 +114,7 @@ Every package that exposes a contract space — published extensions (`packages/
 
 Key rules (these are the spots where mistakes recur, so the convention spells them out explicitly):
 
-- **Author contracts in PSL (`src/contract.prisma`).** PSL is the canonical authoring surface — it reads as a schema (not as builder calls), interoperates with brownfield Prisma schemas, and keeps the contract decoupled from the workspace's TS type system. Wire it with `prismaContract('./src/contract.prisma', { output: 'src/contract.json', target })`. The narrow exception is contracts that need to declare typed objects the PSL surface doesn't yet express (e.g. parameterised `storage.types` base-type registrations like pgvector's `vector` — `types {}` blocks instantiate, they don't register a parameterised base type). Such packages may keep a `src/contract.ts` + `typescriptContract(contract, 'src/contract.json')` config, with a comment in the contract source naming the missing PSL surface.
+- **Author contracts in PSL (`src/contract.prisma`)** when the space contributes app-visible schema (models, storage types, namespaces). PSL is the canonical authoring surface — it reads as a schema (not as builder calls), interoperates with brownfield Prisma schemas, and keeps the contract decoupled from the workspace's TS type system. Wire it with `prismaContract('./src/contract.prisma', { output: 'src/contract.json', target })`. **Migrations-only spaces** that install invariants (e.g. a Postgres extension) but ship no tables or native types of their own omit the source file entirely and wire `emptyContract({ output: 'src/contract.json', target })` in `prisma-next.config.ts` (see `@prisma-next/extension-paradedb`). The narrow **TypeScript** exception is contracts that need to declare typed objects the PSL surface doesn't yet express (e.g. parameterised `storage.types` base-type registrations like pgvector's `vector` — `types {}` blocks instantiate, they don't register a parameterised base type). Such packages keep `src/contract.ts` + `typescriptContract(contract, 'src/contract.json')`, with a comment in the contract source naming the missing PSL surface.
 - **No `<space-id>` subdirectory inside `migrations/`.** A package owns exactly one contract space, so the space-id directory adds no information. Migration directories sit *directly* under `migrations/`, and `refs/` sits at `migrations/refs/`. Configure this with `migrations.dir: 'migrations'` (not `migrations/<space-id>`).
 - **No `src/contract/` subdirectory.** The contract source, emitted `contract.json`, and emitted `contract.d.ts` sit *directly* in `src/`.
 - **`prisma-next.config.ts` is at the package root.** The CLI treats each contract-space package as a self-contained "project"; the in-package config is the source of truth for that project's emit and migration paths.

packages/3-extensions/paradedb/README.md

@@ -75,8 +75,8 @@ ParadeDB BM25 indexes require a `key_field` — a unique column that identifies
 
 The extension's contract + baseline migration are emitted on-disk inside this package using the same pipeline application authors use:
 
-- `pnpm build:contract-space` — runs `prisma-next contract emit` to produce `src/contract.{json,d.ts}` from the PSL source at `src/contract.prisma`.
-- `pnpm exec prisma-next migration plan --name <slug>` (run from this package directory) — scaffolds a new migration directory under `migrations/<dirName>/` for schema changes. **Not chained into `pnpm build`**: `migration plan` is non-idempotent (each invocation generates a new timestamped directory), so it runs manually when the contract source changes. Note: paradedb's contract declares no tables or models, so the planner currently refuses to scaffold the baseline migration (this is **Path B** authoring per [ADR 212](../../../docs/architecture%20docs/adrs/ADR%20212%20-%20Contract%20spaces.md#contract-space-package-layout)). That directory was hand-authored once (Migration subclass + seed `migration.json` preserving the full `toContract`) and `pnpm tsx migrations/<dirName>/migration.ts` re-emits `ops.json` + `migration.json` deterministically. Future migrations that add tables or models can use `migration plan` directly (Path A).
+- `pnpm build:contract-space` — runs `prisma-next contract emit` to produce `src/contract.{json,d.ts}` from `emptyContract({ output: 'src/contract.json', target })` in `prisma-next.config.ts` (migrations-only space: no `contract.prisma` source file).
+- `pnpm exec prisma-next migration plan --name <slug>` (run from this package directory) — scaffolds a new migration directory under `migrations/<dirName>/` for schema changes. **Not chained into `pnpm build`**: `migration plan` is non-idempotent (each invocation generates a new timestamped directory), so it runs manually when the contract changes. Note: paradedb's contract declares no tables or models, so the planner currently refuses to scaffold the baseline migration (this is **Path B** authoring per [ADR 212](../../../docs/architecture%20docs/adrs/ADR%20212%20-%20Contract%20spaces.md#contract-space-package-layout)). That directory was hand-authored once (Migration subclass + seed `migration.json` preserving the full `toContract`) and `pnpm tsx migrations/<dirName>/migration.ts` re-emits `ops.json` + `migration.json` deterministically. Future migrations that add tables or models can use `migration plan` directly (Path A).
 - `pnpm tsx migrations/<dirName>/migration.ts` (run from this package directory) — re-emits `ops.json` + `migration.json` from the hand-edited subclass. Use `tsx`, not bare `node`, because the Migration subclass imports relative TypeScript siblings which Node's native loader can't resolve without a TS-aware loader.
 - `migrations/refs/head.json` is hand-pinned with the latest migration's `to` hash + `providedInvariants`.
 

packages/3-extensions/paradedb/prisma-next.config.ts

@@ -3,8 +3,7 @@
  *
  * The extension package is treated as a self-contained "project" for
  * the CLI: `prisma-next contract emit` writes
- * `<package>/src/contract.{json,d.ts}` (colocated with the
- * `src/contract.prisma` source); `prisma-next migration plan` writes
+ * `<package>/src/contract.{json,d.ts}`; `prisma-next migration plan` writes
  * `<package>/migrations/<dirName>/...`. The descriptor at
  * `src/exports/control.ts` then JSON-imports those artefacts.
  *
@@ -16,14 +15,15 @@
 import postgresAdapter from '@prisma-next/adapter-postgres/control';
 import { defineConfig } from '@prisma-next/cli/config-types';
 import sql from '@prisma-next/family-sql/control';
-import { prismaContract } from '@prisma-next/sql-contract-psl/provider';
+import { emptyContract } from '@prisma-next/sql-contract-ts/config-types';
 import postgres from '@prisma-next/target-postgres/control';
 
 export default defineConfig({
   family: sql,
   target: postgres,
   adapter: postgresAdapter,
-  contract: prismaContract('./src/contract.prisma', {
+  // migrations-only contract space: installs pg_search via migrations, contributes no app-visible schema
+  contract: emptyContract({
     output: 'src/contract.json',
     target: postgres,
   }),