prisma · wmadden · May 1, 2026 · May 1, 2026 · May 1, 2026 · May 1, 2026
diff --git a/docs/README.md b/docs/README.md
@@ -19,6 +19,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-form Pattern E for writing codecs
 - [CLI Style Guide](./CLI%20Style%20Guide.md) — CLI UX conventions
 
 ## Working with AI agents

diff --git a/docs/Testing Guide.md b/docs/Testing Guide.md
@@ -297,7 +297,7 @@ function createStubAdapter(): Adapter<SelectAst, SqlContract<SqlStorage>, Lowere
       target: 'postgres',
       targetFamily: 'sql',
       capabilities: {},
-      codecs: createCodecRegistry(),
+      codecs: emptyCodecRegistry(),
     },
     lower: () => ({ sql: '', params: [] }),
   };

diff --git a/docs/architecture docs/adrs/ADR 152 - Execution Plane Descriptors and Instances.md b/docs/architecture docs/adrs/ADR 152 - Execution Plane Descriptors and Instances.md
@@ -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>
 }
 ```
 

diff --git a/docs/architecture docs/adrs/ADR 184 - Codec-owned value serialization.md b/docs/architecture docs/adrs/ADR 184 - Codec-owned value serialization.md
@@ -1,11 +1,25 @@
 # ADR 184 — Codec-owned value serialization
 
+> **Retrospective note (TML-2357 close-out).** This ADR's examples use
+> the `defineCodec({...})` factory. That factory was the canonical
+> codec-author surface at the time; under TML-2357 it was retired in
+> favor of the class-form Pattern E
+> (`class extends CodecImpl<...>` + `class extends CodecDescriptorImpl<P>`
+> + per-codec column helper). 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 +56,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 +133,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
 

diff --git a/docs/architecture docs/adrs/ADR 186 - Codec-dispatched type rendering.md b/docs/architecture docs/adrs/ADR 186 - Codec-dispatched type rendering.md
@@ -1,5 +1,19 @@
 # ADR 186 — Codec-dispatched type rendering
 
+> **Retrospective note (TML-2357 close-out).** 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
+> TML-2357 retired the `defineCodec({...})` factory in favor of the
+> class-form Pattern E
+> (`class extends CodecDescriptorImpl<P>`). 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 +138,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 +224,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.
 

diff --git a/docs/architecture docs/adrs/ADR 202 - Codec trait system.md b/docs/architecture docs/adrs/ADR 202 - Codec trait system.md
@@ -1,5 +1,20 @@
 # ADR 202 — Codec trait system
 
+> **Retrospective note (TML-2357 close-out).** This ADR's examples
+> show codec definitions via `defineCodec({...})`. The factory was
+> retired under TML-2357 in favor of the class-form Pattern E
+> (`class extends CodecDescriptorImpl<P>`); traits are now declared as
+> `override readonly traits = [...] as const` on the descriptor class.
+> The `'json-validator'` trait this ADR introduced was also retired
+> under TML-2357 — 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 +78,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 +89,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 +118,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'],