prisma · wmadden · May 9, 2026 · May 1, 2026 · May 1, 2026 · May 1, 2026
@@ -0,0 +1,24 @@
+---
+description: Wrap JSDoc / block-comment prose at the same line width as the biome formatter (currently 100). Markdown is exempt — see the markdown-no-artificial-line-wraps skill.
+alwaysApply: false
+---
+
+# JSDoc / block-comment prose — wrap at the biome line width
+
+When adding or editing **prose** in `/** ... */` or long `//` documentation:
+
+1. **Wrap at biome's `lineWidth`** — Wrap prose at the line width configured in `biome.jsonc` (`formatter.lineWidth`, currently **100**). Source of truth: read `biome.jsonc` rather than hard-coding the number; if it changes, this rule changes with it.
+
+2. **No fixed-column wraps below the biome width** — Do not break mid-sentence to stay under ~72 or ~80 characters. Editors soft-wrap; arbitrary narrow wraps make diffs noisy and conflict-prone.
+
+3. **Bullet lists and tagged blocks**
+   - **Bullets** (`*` / `-`): keep each bullet's prose on one line up to the biome width before wrapping; wrap continuation lines aligned with the bullet text.
+   - **Tagged blocks** (`@param`, `@returns`, `@example`): follow normal JSDoc conventions; the same line-width rule applies to the sentence text.
+
+4. **Orphaned blocks** — A doc comment must document the declaration that immediately follows it (after optional blank lines only before `import` / file headers). Do not leave a standalone `/** ... */` between imports and the next export with no attached symbol; merge into the relevant declaration's doc or delete redundancy.
+
+5. **Markdown is exempt** — Do not apply this rule to `.md` files (READMEs, ADRs, PR bodies, rulecards). Markdown prose stays on one continuous line per paragraph; see `.agents/skills/markdown-no-artificial-line-wraps/SKILL.md`. ADR callouts and narrative Markdown under `docs/architecture docs/adrs/` follow the Markdown rule, not this one.
+
+6. **Rationale** — Wrapping at the same width that the formatter uses keeps doc-comment prose visually consistent with surrounding code, avoids both "one giant line" and "narrow 1990s terminal" extremes, and produces stable diffs because the wrap width is anchored to the formatter rather than picked per-author.
+
+Related: `.agents/skills/markdown-no-artificial-line-wraps/SKILL.md` (Markdown files).
@@ -75,6 +75,7 @@ Thresholds are defined in `.cursor/rules-footprint.config.json`.
 
 ## TypeScript & Typing
 - `.cursor/rules/typescript-patterns.mdc` — TS patterns index (short)
+- `.agents/rules/jsdoc-no-artificial-line-wraps.mdc` — JSDoc prose: no manual ~80-column wraps; avoid orphaned doc blocks
 - `.cursor/rules/generic-parameters.mdc` — Generic parameter defaults
 - `.cursor/rules/interface-factory-pattern.mdc` — Interface-based design + factories
 - `.cursor/rules/type-predicates.mdc` — Replace blind casts with type predicates

@@ -1,5 +1,5 @@
 {
-  "cSpell.words": ["codegen", "Lowerer", "pgvector"],
+  "cSpell.words": ["arktype", "codegen", "Lowerer", "pgvector"],
   "editor.defaultFormatter": "biomejs.biome",
   "typescript.tsdk": "node_modules/typescript/lib",
   "[typescript]": {

@@ -23,6 +23,7 @@ This directory contains the primary documentation for the repository.
 - [Glossary](./glossary.md) — user-facing terminology (source of truth for naming)
 - [Commands](./commands/README.md) — command docs and entry points
 - [Reference docs](./reference/) — conventions and patterns used across the codebase
+- [Codec authoring guide](./reference/codec-authoring-guide.md) — class-based codecs (`CodecImpl`, `CodecDescriptorImpl`) and column helpers
 - [CLI Style Guide](./CLI%20Style%20Guide.md) — CLI UX conventions
 
 ## Working with AI agents

@@ -297,7 +297,7 @@ function createStubAdapter(): Adapter<SelectAst, SqlContract<SqlStorage>, Lowere
       target: 'postgres',
       targetFamily: 'sql',
       capabilities: {},
-      codecs: createCodecRegistry(),
+      codecs: emptyCodecRegistry(),
     },
     lower: () => ({ sql: '', params: [] }),
   };
@@ -330,10 +330,7 @@ Low-level helper tests (for IR builders, planners, CLI glue, etc.) should prove
 
 ### File Organization
 
-**Unit tests:** `src/**/*.test.ts` (alongside source code)
-**Integration tests:** `test/**/*.integration.test.ts` or `src/**/*.integration.test.ts`
-**Type tests:** `src/**/*.test-d.ts` (type-level tests using `expectTypeOf`)
-**E2E tests:** `test/e2e/framework/test/**/*.test.ts`
+**Unit tests:** `src/**/*.test.ts` (alongside source code) **Integration tests:** `test/**/*.integration.test.ts` or `src/**/*.integration.test.ts` **Type tests:** `src/**/*.test-d.ts` (type-level tests using `expectTypeOf`) **E2E tests:** `test/e2e/framework/test/**/*.test.ts`
 
 ### Test File Structure
 
@@ -969,9 +966,7 @@ it('reads user', async () => {
 
 ### 6. Use Appropriate Test Level
 
-**Unit test:** Test a single function in isolation
-**Integration test:** Test multiple components working together
-**E2E test:** Test complete execution path to database and back
+**Unit test:** Test a single function in isolation **Integration test:** Test multiple components working together **E2E test:** Test complete execution path to database and back
 
 **When in doubt:** Start with a unit test. If you need to test interactions, create an integration test. If you need to test the complete flow, create an E2E test.
 

@@ -164,9 +164,8 @@ The SQL family extends base execution-plane descriptors with `SqlStaticContribut
 
 ```ts
 interface SqlStaticContributions {
-  codecs(): CodecRegistry
+  codecs(): ReadonlyArray<CodecDescriptor>
   operationSignatures(): ReadonlyArray<SqlOperationSignature>
-  parameterizedCodecs(): ReadonlyArray<RuntimeParameterizedCodecDescriptor>
 }
 ```
 

@@ -1,6 +1,6 @@
 # ADR 180 — Dot-path field accessor
 
-> **Implementation update (Mongo query builder unification).** The consolidated `FieldAccessor` shipped in `@prisma-next/mongo-query-builder` replaced the earlier `FieldProxy` and `FilterProxy` types — filter and update operators now hang off a single accessor, used by both read callbacks (`match`, `addFields`, `project`, `group`) and write callbacks (`updateMany`, `findOneAndUpdate`, etc.). Type-safe dot-path validation for the callable form `f("address.city")` was implemented in [TML-2281](https://linear.app/prisma-company/issue/TML-2281): a second generic `N extends NestedDocShape` threads the contract's model + value-object structure through the pipeline, paths are constrained by `ValidPaths<N>`, the resolved leaf's codec drives the returned `Expression`, and non-leaf paths surface a reduced `ObjectExpression` operator surface. Additive pipeline stages preserve `N`; replacement stages (`project`, `group`, `replaceRoot`, …) reset it, disabling the callable form downstream. For paths that are intentionally outside the typed model (canonically, migration authoring where a backfill writes a field that is not yet in the contract), `f.rawPath("path")` is the sanctioned escape hatch — it returns a `LeafExpression<DocField>` with the verbatim path and the full leaf operator surface. The method is named `rawPath` rather than `raw` so the escape hatch does not shadow a legitimate top-level `raw` field on a user model (the callable fallback `f("raw")` is disabled downstream of replacement stages, which would otherwise leave such a field inaccessible).
+> **Implementation update (Mongo query builder unification).** The consolidated `FieldAccessor` shipped in `@prisma-next/mongo-query-builder` replaced the earlier `FieldProxy` and `FilterProxy` types — filter and update operators now hang off a single accessor, used by both read callbacks (`match`, `addFields`, `project`, `group`) and write callbacks (`updateMany`, `findOneAndUpdate`, etc.). Type-safe dot-path validation for the callable form `f("address.city")` added a second generic `N extends NestedDocShape` that threads the contract's model + value-object structure through the pipeline, constrains paths by `ValidPaths<N>`, drives the returned `Expression` from the resolved leaf's codec, and surfaces a reduced `ObjectExpression` operator surface for non-leaf paths. Additive pipeline stages preserve `N`; replacement stages (`project`, `group`, `replaceRoot`, …) reset it, disabling the callable form downstream. For paths that are intentionally outside the typed model (canonically, migration authoring where a backfill writes a field that is not yet in the contract), `f.rawPath("path")` is the sanctioned escape hatch — it returns a `LeafExpression<DocField>` with the verbatim path and the full leaf operator surface. The method is named `rawPath` rather than `raw` so the escape hatch does not shadow a legitimate top-level `raw` field on a user model (the callable fallback `f("raw")` is disabled downstream of replacement stages, which would otherwise leave such a field inaccessible).
 
 ## At a glance
 

@@ -1,11 +1,13 @@
 # ADR 184 — Codec-owned value serialization
 
+> **Retrospective note.** This ADR's examples use the `defineCodec({...})` factory. That factory was the canonical codec-author surface at the time; it was later retired in favor of class-based authoring: concrete codecs extend `CodecImpl`, descriptors extend `CodecDescriptorImpl`, and per-codec column helpers tie helpers to descriptors with `satisfies`. The ADR's *decision* — that codecs own both wire and JSON-safe representations through `encode` / `decode` + `encodeJson` / `decodeJson` — is unchanged; only the authoring shape has moved on. See [ADR 208 — Higher-order codecs for parameterized types](ADR%20208%20-%20Higher-order%20codecs%20for%20parameterized%20types.md) and the [Codec authoring guide](../../reference/codec-authoring-guide.md) for the current shape.
+
 ## At a glance
 
 A column with `codecId: "pg/timestamptz@1"` has a default value of `new Date('2024-01-15')` — a JavaScript `Date`. This value has to survive a round-trip through `contract.json`, but `Date` has no JSON representation. The codec handles it:
 
 ```ts
-const pgTimestamptzCodec = codec({
+const pgTimestamptzCodec = defineCodec({
   typeId: 'pg/timestamptz@1',
   targetTypes: ['timestamptz'],
   traits: ['equality', 'order'],
@@ -42,7 +44,7 @@ The resulting contract JSON is plain — no tags, no wrappers:
 
 The consumer reads `"2024-01-15T00:00:00.000Z"`, looks up `pg/timestamptz@1`, calls `decodeJson(...)`, gets a `Date` object.
 
-Every codec has `encodeJson` and `decodeJson`. For JSON-safe types (strings, numbers, booleans, null), they are identity functions — the `codec()` factory provides these defaults. Only codecs for types that JSON can't represent (`Date`, binary data, etc.) override them.
+Every codec has `encodeJson` and `decodeJson`. For JSON-safe types (strings, numbers, booleans, null), they are identity functions — the `defineCodec()` factory provides these defaults. Only codecs for types that JSON can't represent (`Date`, binary data, etc.) override them.
 
 The same typed value crosses other boundaries too. The migration planner renders it into DDL (`DEFAULT '2024-01-15T00:00:00.000Z'`). The PSL printer renders it into schema source (`@default("2024-01-15T00:00:00.000Z")`). Migration operations carry it in `ops.json`. These are the same problem for different media, but they live at different layers:
 
@@ -119,7 +121,7 @@ Both SQL and Mongo families define structurally identical codec interfaces (`Cod
 
 `encodeJson` and `decodeJson` are required on the `Codec` interface, not optional. Any type that can appear in the contract may need a literal value serialized for it (column defaults, discriminator values, type parameters, migration temporary defaults). Making the methods required eliminates null checks at every dispatch site.
 
-For JSON-safe types (strings, numbers, booleans, null), the methods are identity functions. The `codec()` factory provides these defaults when not explicitly supplied, so codecs for JSON-safe types need no additional boilerplate.
+For JSON-safe types (strings, numbers, booleans, null), the methods are identity functions. The `defineCodec()` factory provides these defaults when not explicitly supplied, so codecs for JSON-safe types need no additional boilerplate.
 
 ### Contract loading integrates decoding
 

@@ -1,5 +1,7 @@
 # ADR 186 — Codec-dispatched type rendering
 
+> **Retrospective note.** This ADR introduced the `renderOutputType` slot on the codec record (and shows `defineCodec({...})` examples). Both the codec authoring shape and the home of `renderOutputType` have since moved on: [ADR 208](ADR%20208%20-%20Higher-order%20codecs%20for%20parameterized%20types.md) relocated `renderOutputType` to the unified `CodecDescriptor`, and the `defineCodec({...})` factory was retired in favor of class-based descriptors (`CodecDescriptorImpl`) and codecs (`CodecImpl`). The decision this ADR records — that the codec is the dispatch authority for type rendering — is unchanged; only the slot's home and the authoring syntax have moved. See [Codec authoring guide](../../reference/codec-authoring-guide.md).
+
 ## At a glance
 
 A `vector(1536)` column should produce `Vector<1536>` as its output type. A `jsonb(schema)` column should produce `{ name: string }`. Today, resolving a field's output type requires dispatching through `CodecTypes[codecId]['output']` or `parameterizedOutput` — a hoop that varies depending on whether the codec is parameterized. After this change, every field's output type is resolved once and stamped into a dedicated map in `contract.d.ts`:
@@ -124,7 +126,7 @@ Non-parameterized codecs don't need to implement it. The common case is zero cod
 Here's what the JSONB codec looks like with `renderOutputType`:
 
 ```ts
-const pgJsonbCodec = codec({
+const pgJsonbCodec = defineCodec({
   typeId: 'pg/jsonb@1',
   targetTypes: ['jsonb'],
   encode: (value): string => JSON.stringify(value),
@@ -210,7 +212,7 @@ Rejected because phantom types are gross, and mixing type-only metadata into the
 
 ### Make `renderOutputType` required with a default
 
-Like `encodeJson`/`decodeJson` on [ADR 184](ADR%20184%20-%20Codec-owned%20value%20serialization.md), make it required with a default provided by the `codec()` factory.
+Like `encodeJson`/`decodeJson` on [ADR 184](ADR%20184%20-%20Codec-owned%20value%20serialization.md), make it required with a default provided by the `defineCodec()` factory.
 
 Deferred. Most codecs don't parameterize their output type — the default (`CodecTypes[codecId]['output']`) handles them. Optional with a well-defined fallback is cleaner for now.
 

@@ -1,5 +1,7 @@
 # ADR 202 — Codec trait system
 
+> **Retrospective note.** This ADR's examples show codec definitions via `defineCodec({...})`. That factory was retired in favor of class-based descriptors (`CodecDescriptorImpl`); traits are now declared as `override readonly traits = [...] as const` on the descriptor class. The `'json-validator'` trait this ADR introduced was also retired — JSON-Schema validation now lives uniformly inside the resolved codec's `decode` body rather than behind a parallel `JsonSchemaValidatorRegistry`. The trait system itself, the operator-gating semantics, and the canonical traits set are all unchanged. See [ADR 208](ADR%20208%20-%20Higher-order%20codecs%20for%20parameterized%20types.md) and the [Codec authoring guide](../../reference/codec-authoring-guide.md).
+
 ## Context
 
 Data types in the system are identified by codec IDs (e.g., `pg/int4@1`, `pg/text@1`, `pg/vector@1`). Query surfaces need to know which operators and functions are valid for a given data type — for example, ordering a `jsonb` column with `lt` or applying `sum` to a `text` column are not meaningful SQL. Today there is no generic mechanism to express these semantic constraints.
@@ -63,7 +65,7 @@ Traits are declared at codec registration time. Core SQL codecs and adapter code
 
 ```ts
 // sql-codecs.ts
-const sqlIntCodec = codec({
+const sqlIntCodec = defineCodec({
   typeId: SQL_INT_CODEC_ID,
   targetTypes: ['int'],
   traits: ['equality', 'order', 'numeric'],
@@ -74,23 +76,23 @@ const sqlIntCodec = codec({
 
 ```ts
 // postgres adapter codecs
-const pgTextCodec = codec({
+const pgTextCodec = defineCodec({
   typeId: 'pg/text@1',
   targetTypes: ['text'],
   traits: ['equality', 'order', 'textual'],
   encode: (value) => value,
   decode: (wire) => wire,
 });
 
-const pgBoolCodec = codec({
+const pgBoolCodec = defineCodec({
   typeId: 'pg/bool@1',
   targetTypes: ['bool'],
   traits: ['equality', 'boolean'],
   encode: (value) => value,
   decode: (wire) => wire,
 });
 
-const pgJsonbCodec = codec({
+const pgJsonbCodec = defineCodec({
   typeId: 'pg/jsonb@1',
   targetTypes: ['jsonb'],
   traits: ['equality'],  // equality only; not order-comparable
@@ -103,7 +105,7 @@ Extension codecs declare traits the same way:
 
 ```ts
 // pgvector codec — vectors have equality but are not order-comparable or numeric
-const pgVectorCodec = codec({
+const pgVectorCodec = defineCodec({
   typeId: 'pg/vector@1',
   targetTypes: ['vector'],
   traits: ['equality'],