TML-3061: PostgreSQL and SQLite codec descriptor protocols by tensordreams · Pull Request #1051 · prisma/prisma-next

tensordreams · 2026-07-24T06:55:03Z

Linked issue

Base: main. Predecessor #1023 is merged, so this PR has no stacked-base prerequisite.

At a glance

nativeTypeFor(ref: CodecRef): string {
  return this.nativeType(this.validateParams(ref));
}

projectJson(expression: ProjectionExpr, ref: CodecRef): ProjectionExpr {
  const params = this.validateParams(ref);
  return ref.many === true
    ? this.jsonArrayProjection(expression, params)
    : this.jsonProjection(expression, params);
}

A PostgreSQL descriptor now accepts the generic CodecRef that survives framework composition, validates its erased parameters, and enters target-owned typed behavior only after validation.

Decision

This PR ships the public PostgreSQL and SQLite codec descriptor protocols that the lossless JSON projection work will execute through: explicit generic-to-target adapters, narrow authoring helpers, structurally validated immutable registries, and coherent runtime/control adapter composition. It migrates every affected built-in and the pgvector, PostGIS, and arktype-json extensions to those protocols, moves PostgreSQL native-type lookup behind the validated descriptor boundary, and adds the PublicCodecTypes declaration-portability boundary plus extension-author migration guidance.

Reviewer notes

The JSON projection hooks are public protocol capabilities, but production PostgreSQL and SQLite renderers deliberately remain pass-through. TML-3063 will activate descriptor dispatch and own the observable lossless JSON hard cut.
Codec JSON methods, emitted contracts, generated declarations, fixtures, codec IDs, and current SQL/JSON representations are unchanged. Drift in any of those surfaces was treated as a stop condition.
PublicCodecTypes intentionally exposes only each codec's input, output, and traits through composed contract declarations. This keeps downstream semantic typing exact without making exported declarations name concrete target descriptor implementation members.
PostgreSQL extension authors must adopt the target protocol and add the target package as a runtime dependency; direct adapter injection also moves to target-typed codecDescriptors.
Deterministic target, adapter, extension, declaration, workspace, documentation, skill, manifest, dependency, cast, throw, upgrade, fixture, and audit gates passed. The broad package, integration, and e2e suites were also run, but Postgres/resource-related flakes remained after varying and focused reruns, so their final broad confirmation is CI-deferred and is not claimed green here.

How it fits together

PostgresCodecDescriptor and SqliteCodecDescriptor add stable structural discriminants and public template methods. Each template method validates erased CodecRef.typeParams through the descriptor's Standard Schema before calling a strongly typed target hook.
postgresCodec(...), sqliteCodec(...), definePostgresCodecs(...), and defineSqliteCodecs(...) make target ownership explicit while preserving generic SQL descriptor IDs, traits, parameter schemas, factories, renderers, metadata, and literal types. PostgreSQL supplies native-type plus scalar/array projection capabilities; SQLite supplies scalar projection and reports unsupported stored scalar-array refs.
Target, adapter, and ordered extension contributions are collected once per construction plane. The PostgreSQL and SQLite builders structurally validate that set, reject malformed, wrong-target, raw, or duplicate descriptors, and derive ordinary materialization plus target lookup from the same immutable registry.
PostgreSQL parameter rendering now resolves trusted native type names through nativeTypeFor(ref) on the validated descriptor. Runtime, control, custom, enum, extension, and array cast spellings remain pinned to their existing SQL.
PublicCodecTypes projects extension codec maps to their public semantic fields before they enter contract types. Consumer declarations retain exact application types and traits while staying portable across package boundaries.
The codec authoring guide and the upgrade entry under skills/extension-author/prisma-next-extension-upgrade/upgrades/0.16-to-0.17/ document target-owned authoring, coherent contribution sets, parameter-ref audits, and the dormant-hook transition.

Behavior changes & evidence

Extension authors can define and contribute target-owned PostgreSQL and SQLite codecs through public APIs. The protocols validate erased refs before typed behavior, preserve concrete tuple/factory typing, and use structural validation across separately loaded packages. Implementation: PostgreSQL descriptor protocol, SQLite descriptor protocol. Evidence: PostgreSQL runtime tests, SQLite runtime tests.
PostgreSQL arrays have a target-owned default projection shape, while SQLite rejects undefined stored scalar-array semantics. PostgreSQL's default lift binds the source once and preserves null arrays, empty arrays, null elements, and ordinality; SQLite raises a structured error for CodecRef.many. Implementation: PostgreSQL descriptor protocol, SQLite descriptor protocol. Evidence: PostgreSQL descriptor tests, SQLite descriptor tests.
Runtime, control, and direct adapter paths now see one coherent descriptor set and fail invalid composition early. Bare adapters remain built-ins-only; stack composition includes ordered target, adapter, and extension contributions. Implementation: PostgreSQL registry assembly, SQLite registry assembly. Evidence: PostgreSQL composition tests, SQLite composition tests.
First-party PostgreSQL extensions use one canonical target-typed contribution set. pgvector, PostGIS, and arktype-json expose the same descriptor arrays through runtime and control metadata while retaining current factories, application types, vector text, HEXEWKB, and structured JSON representations. Implementation: pgvector codecs, PostGIS codecs, arktype-json codec. Evidence: pgvector adoption tests, PostGIS adoption tests.
Consumer-exported contracts remain declaration-portable. Extension codec maps retain exact public input/output/trait semantics without exposing target descriptor implementation structure. Implementation: PublicCodecTypes. Evidence: declaration fixture, declaration type test.
Current rendering remains unchanged while the new hooks stay dormant. PostgreSQL and SQLite still render codec, native, and document projections as their wrapped expressions; composition tests assert exact existing JSON SQL and zero descriptor projection calls. Implementation: PostgreSQL JSON visitor, SQLite JSON visitor. Evidence: PostgreSQL composition tests, SQLite composition tests.

Compatibility / migration / risk

This is a pre-1.0 public SPI change for PostgreSQL-bound extension codecs. Extension descriptors must extend PostgresCodecDescriptor or use postgresCodec(...), define target behavior, contribute a definePostgresCodecs(...) set through runtime and control paths, and declare @prisma-next/target-postgres as a production dependency.
PostgreSQL direct adapter options now accept target-typed codecDescriptors in place of an independently assembled generic codecLookup; SQLite gains the equivalent target-typed option.
Invalid dynamic composition now fails during adapter construction. Raw generic, wrong-target, structurally malformed, and duplicate descriptors no longer survive until lookup or query lowering.
PublicCodecTypes narrows incidental descriptor-derived members out of exported contract types while preserving input, output, and traits. Consumers depending on incidental implementation members through contract types must move to the descriptor API.
There is no data, emitted-contract, codec-ID, codec JSON, or fixture migration in this PR. Production JSON projection remains pass-through until TML-3063.

Testing performed

Passed on the final branch state:

Deterministic build, runtime test, typecheck, and lint gates for PostgreSQL/SQLite targets, PostgreSQL/SQLite adapters, pgvector, PostGIS, and arktype-json.
Root pnpm build and pnpm typecheck.
Runtime/type coverage for descriptor validation, target tuple preservation, adapter composition, native-type/cast parity, dormant JSON hooks, extension adoption, and PublicCodecTypes declaration portability.
Documentation, skill, and package-manifest validation; pnpm lint:deps; pnpm lint:casts; pnpm lint:throws; pnpm check:upgrade-coverage --mode pr; pnpm fixtures:check; and the bounded closing audits.

Run, with final broad confirmation deferred to CI:

pnpm test:packages
pnpm test:integration
pnpm test:e2e

Postgres/resource-related flakes remained after reruns at varying and focused scopes. These three broad suites are recorded as executed, not as passing.

Skill update

Updated the codec authoring documentation and the extension-author upgrade instructions in skills/extension-author/prisma-next-extension-upgrade/upgrades/0.16-to-0.17/. The upgrade entry detects generic PostgreSQL extension descriptors and walks authors through runtime dependency placement, target subclassing or adaptation, canonical runtime/control contribution sets, required CodecRef.typeParams, and behavior-preservation checks.

Follow-ups

TML-3063 will activate descriptor JSON projection dispatch, land the lossless PostgreSQL/SQLite and extension representations, and remove transitional generic metadata after production consumers have moved.

Alternatives considered

Keep target behavior in generic CodecMeta or add a framework-owned target map. Rejected because target SQL/JSON behavior is open-world and belongs to each target package; generic framework composition remains target-neutral.
Validate descriptors with instanceof. Rejected because extensions may load a separate copy of a target package. Stable structural discriminants and required methods preserve interoperability across module identities.
Maintain separate ordinary and target registries. Rejected because the two views could disagree about membership, factories, or behavior. Both views are now derived from one validated descriptor set.
Make identity JSON projection an implicit default. Rejected because omission would silently assert that the database representation is already lossless. Every descriptor states the transitional behavior explicitly.
Activate JSON projection hooks in this PR. Rejected so registry/authoring migration and representation changes remain independently reviewable. TML-3063 owns the observable hard cut.

Checklist

All commits are signed off (git commit -s) per the DCO.
I read CONTRIBUTING.md and the change is scoped to one logical concern.
Tests are updated for the public protocols, composition boundary, extensions, declaration portability, and unchanged rendering behavior.
The PR title is in TML-NNNN: <sentence-case title> form and names the concrete deliverable.
The Skill update section is filled in.

Summary by CodeRabbit

New Features
- Added PostgreSQL- and SQLite-specific codec descriptor authoring APIs, including descriptor/codec registries and validation.
- Adapters now use provided target-specific codec descriptor sets to keep runtime and control-plane behavior consistent.
- Improved native type handling and JSON projection behavior for parameterized and scalar-array scenarios.
Bug Fixes
- PostGIS geometry codecs now support optional SRID, with updated typing, validation, and output rendering.
Documentation
- Expanded codec authoring guide, target READMEs, and 0.16 → 0.17 upgrade instructions for adopting the new descriptor model.

coderabbitai · 2026-07-24T06:55:43Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7b145ecf-a71d-45ef-88d1-4f186290d1c8

📥 Commits

Reviewing files that changed from the base of the PR and between 310318b and 33f0ffc.

📒 Files selected for processing (1)

docs/reference/codec-authoring-guide.md

🚧 Files skipped from review as they are similar to previous changes (1)

docs/reference/codec-authoring-guide.md

📝 Walkthrough

Walkthrough

The PR adds target-owned PostgreSQL and SQLite codec descriptor protocols and registries, rewires runtime/control adapters to use composed descriptor registries, migrates built-in and extension codecs, and documents authoring and upgrade paths.

Changes

Descriptor contracts and built-ins

Layer / File(s)	Summary
Target descriptor protocols `packages/3-targets/3-targets/postgres/src/core/codec-descriptor.ts`, `packages/3-targets/3-targets/sqlite/src/core/codec-descriptor.ts`	Adds target-specific descriptor bases, adapters, structural validation, immutable registries, duplicate detection, and JSON projection rules.
Built-in descriptors and exports `packages/3-targets/3-targets/{postgres,sqlite}/src/**`	Migrates built-in descriptors to target-owned protocols, adds native type/projection hooks, and exposes descriptor APIs and registries.

Adapter composition

Layer / File(s)	Summary
PostgreSQL adapter registry flow `packages/3-targets/6-adapters/postgres/src/**`	Builds composed registries from target, adapter, and extension descriptors and uses them for codec materialization and SQL casts.
SQLite adapter registry flow `packages/3-targets/6-adapters/sqlite/src/**`	Builds target-specific registries for runtime and control adapters, including contributed descriptors and validation.

Extension and authoring updates

Layer / File(s)	Summary
Extension migrations `packages/3-extensions/{arktype-json,pgvector,postgis}/**`	Migrates PostgreSQL descriptors, preserves native/projection behavior, and supplies parameterized codec references.
Documentation and type coverage `docs/reference/`, `skills/extension-author/`, `packages/2-sql/`, `packages/3-targets//test/**`	Documents descriptor authoring and migration rules and adds compile-time and runtime coverage for descriptor identity, registries, projections, and codec behavior.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs

prisma/prisma-next#807: Related control-path refactoring from codec lookups to codec registries.
prisma/prisma-next#1034: Related PostgreSQL typed-parameter cast rendering.

Suggested reviewers: wmadden

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: introducing PostgreSQL and SQLite codec descriptor protocols.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch tml-3061-target-codec-descriptor-foundations

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

pkg-pr-new · 2026-07-24T06:58:17Z

Open in StackBlitz

@prisma-next/extension-author-tools

npm i https://pkg.pr.new/@prisma-next/extension-author-tools@1051

@prisma-next/mongo-runtime

npm i https://pkg.pr.new/@prisma-next/mongo-runtime@1051

@prisma-next/family-mongo

npm i https://pkg.pr.new/@prisma-next/family-mongo@1051

@prisma-next/sql-runtime

npm i https://pkg.pr.new/@prisma-next/sql-runtime@1051

@prisma-next/family-sql

npm i https://pkg.pr.new/@prisma-next/family-sql@1051

@prisma-next/extension-arktype-json

npm i https://pkg.pr.new/@prisma-next/extension-arktype-json@1051

@prisma-next/middleware-cache

npm i https://pkg.pr.new/@prisma-next/middleware-cache@1051

@prisma-next/mongo

npm i https://pkg.pr.new/@prisma-next/mongo@1051

@prisma-next/extension-paradedb

npm i https://pkg.pr.new/@prisma-next/extension-paradedb@1051

@prisma-next/extension-pgvector

npm i https://pkg.pr.new/@prisma-next/extension-pgvector@1051

@prisma-next/extension-postgis

npm i https://pkg.pr.new/@prisma-next/extension-postgis@1051

@prisma-next/postgres

npm i https://pkg.pr.new/@prisma-next/postgres@1051

@prisma-next/sql-orm-client

npm i https://pkg.pr.new/@prisma-next/sql-orm-client@1051

@prisma-next/sqlite

npm i https://pkg.pr.new/@prisma-next/sqlite@1051

@prisma-next/extension-supabase

npm i https://pkg.pr.new/@prisma-next/extension-supabase@1051

@prisma-next/target-mongo

npm i https://pkg.pr.new/@prisma-next/target-mongo@1051

@prisma-next/adapter-mongo

npm i https://pkg.pr.new/@prisma-next/adapter-mongo@1051

@prisma-next/driver-mongo

npm i https://pkg.pr.new/@prisma-next/driver-mongo@1051

@prisma-next/contract

npm i https://pkg.pr.new/@prisma-next/contract@1051

@prisma-next/utils

npm i https://pkg.pr.new/@prisma-next/utils@1051

@prisma-next/config

npm i https://pkg.pr.new/@prisma-next/config@1051

@prisma-next/errors

npm i https://pkg.pr.new/@prisma-next/errors@1051

@prisma-next/framework-components

npm i https://pkg.pr.new/@prisma-next/framework-components@1051

@prisma-next/operations

npm i https://pkg.pr.new/@prisma-next/operations@1051

@prisma-next/ts-render

npm i https://pkg.pr.new/@prisma-next/ts-render@1051

@prisma-next/contract-authoring

npm i https://pkg.pr.new/@prisma-next/contract-authoring@1051

@prisma-next/ids

npm i https://pkg.pr.new/@prisma-next/ids@1051

@prisma-next/psl-parser

npm i https://pkg.pr.new/@prisma-next/psl-parser@1051

@prisma-next/psl-printer

npm i https://pkg.pr.new/@prisma-next/psl-printer@1051

@prisma-next/cli

npm i https://pkg.pr.new/@prisma-next/cli@1051

@prisma-next/cli-telemetry

npm i https://pkg.pr.new/@prisma-next/cli-telemetry@1051

@prisma-next/config-loader

npm i https://pkg.pr.new/@prisma-next/config-loader@1051

@prisma-next/emitter

npm i https://pkg.pr.new/@prisma-next/emitter@1051

@prisma-next/language-server

npm i https://pkg.pr.new/@prisma-next/language-server@1051

@prisma-next/migration-tools

npm i https://pkg.pr.new/@prisma-next/migration-tools@1051

prisma-next

npm i https://pkg.pr.new/prisma-next@1051

@prisma-next/vite-plugin-contract-emit

npm i https://pkg.pr.new/@prisma-next/vite-plugin-contract-emit@1051

@prisma-next/mongo-codec

npm i https://pkg.pr.new/@prisma-next/mongo-codec@1051

@prisma-next/mongo-contract

npm i https://pkg.pr.new/@prisma-next/mongo-contract@1051

@prisma-next/mongo-value

npm i https://pkg.pr.new/@prisma-next/mongo-value@1051

@prisma-next/mongo-contract-psl

npm i https://pkg.pr.new/@prisma-next/mongo-contract-psl@1051

@prisma-next/mongo-contract-ts

npm i https://pkg.pr.new/@prisma-next/mongo-contract-ts@1051

@prisma-next/mongo-emitter

npm i https://pkg.pr.new/@prisma-next/mongo-emitter@1051

@prisma-next/mongo-schema-ir

npm i https://pkg.pr.new/@prisma-next/mongo-schema-ir@1051

@prisma-next/mongo-query-ast

npm i https://pkg.pr.new/@prisma-next/mongo-query-ast@1051

@prisma-next/mongo-orm

npm i https://pkg.pr.new/@prisma-next/mongo-orm@1051

@prisma-next/mongo-query-builder

npm i https://pkg.pr.new/@prisma-next/mongo-query-builder@1051

@prisma-next/mongo-lowering

npm i https://pkg.pr.new/@prisma-next/mongo-lowering@1051

@prisma-next/mongo-wire

npm i https://pkg.pr.new/@prisma-next/mongo-wire@1051

@prisma-next/sql-contract

npm i https://pkg.pr.new/@prisma-next/sql-contract@1051

@prisma-next/sql-errors

npm i https://pkg.pr.new/@prisma-next/sql-errors@1051

@prisma-next/sql-operations

npm i https://pkg.pr.new/@prisma-next/sql-operations@1051

@prisma-next/sql-schema-ir

npm i https://pkg.pr.new/@prisma-next/sql-schema-ir@1051

@prisma-next/sql-contract-psl

npm i https://pkg.pr.new/@prisma-next/sql-contract-psl@1051

@prisma-next/sql-contract-ts

npm i https://pkg.pr.new/@prisma-next/sql-contract-ts@1051

@prisma-next/sql-contract-emitter

npm i https://pkg.pr.new/@prisma-next/sql-contract-emitter@1051

@prisma-next/sql-lane-query-builder

npm i https://pkg.pr.new/@prisma-next/sql-lane-query-builder@1051

@prisma-next/sql-relational-core

npm i https://pkg.pr.new/@prisma-next/sql-relational-core@1051

@prisma-next/sql-builder

npm i https://pkg.pr.new/@prisma-next/sql-builder@1051

@prisma-next/target-postgres

npm i https://pkg.pr.new/@prisma-next/target-postgres@1051

@prisma-next/target-sqlite

npm i https://pkg.pr.new/@prisma-next/target-sqlite@1051

@prisma-next/adapter-postgres

npm i https://pkg.pr.new/@prisma-next/adapter-postgres@1051

@prisma-next/adapter-sqlite

npm i https://pkg.pr.new/@prisma-next/adapter-sqlite@1051

@prisma-next/driver-postgres

npm i https://pkg.pr.new/@prisma-next/driver-postgres@1051

@prisma-next/driver-sqlite

npm i https://pkg.pr.new/@prisma-next/driver-sqlite@1051

commit: 33f0ffc

github-actions · 2026-07-24T06:58:52Z

size-limit report 📦

Path	Size
postgres / no-emit	170.18 KB (+1.08% 🔺)
postgres / emit	150.83 KB (+1.1% 🔺)
mongo / no-emit	100.72 KB (0%)
mongo / emit	90.4 KB (0%)
cf-worker / no-emit	195.84 KB (+1.05% 🔺)
cf-worker / emit	174.68 KB (+1.2% 🔺)

coderabbitai

🧹 Nitpick comments (2)

packages/3-targets/3-targets/sqlite/test/typed-descriptor-flow.test-d.ts (1)
5-15: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Import AnySqliteCodecDescriptor from the public exports surface, not core.

This file imports AnySqliteCodecDescriptor from ../src/core/codec-descriptor, but the type is already re-exported from ../src/exports/codec-descriptor (used by the sibling test files sqlite-codec-descriptor.test.ts/.test-d.ts). Importing from core bypasses the package's intended public API boundary.
♻️ Suggested fix
-import type { AnySqliteCodecDescriptor } from '../src/core/codec-descriptor';
+import type { AnySqliteCodecDescriptor } from '../src/exports/codec-descriptor';
Based on learnings, "treat files there as explicit public API export surfaces rather than internal barrels... ensure the exports in src/exports accurately represent the public API."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/3-targets/3-targets/sqlite/test/typed-descriptor-flow.test-d.ts`
around lines 5 - 15, Update the AnySqliteCodecDescriptor import in the typed
descriptor flow test to use the public export from
../src/exports/codec-descriptor instead of the internal
../src/core/codec-descriptor module, while leaving the other imports unchanged.
Source: Learnings
packages/3-targets/3-targets/postgres/src/core/codecs.ts (1)
191-197: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Optional: consider a shared identity jsonProjection to cut repetition.

The identical jsonProjection(expression) { return expression; } override is repeated across ~25 scalar descriptor classes. If the intent is a per-codec authoring decision, keeping it explicit is fine; otherwise a default identity implementation on PostgresCodecDescriptor (or reusing the module-level identityJsonProjection) would remove the boilerplate while keeping array/custom projections overridable.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/3-targets/3-targets/postgres/src/core/codecs.ts` around lines 191 -
197, Optionally remove the repeated identity jsonProjection override from scalar
descriptor classes such as PgTextDescriptor by providing the default identity
implementation on PostgresCodecDescriptor or reusing identityJsonProjection.
Preserve explicit overrides for array or custom projection descriptors.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@packages/3-targets/3-targets/postgres/src/core/codecs.ts`:
- Around line 191-197: Optionally remove the repeated identity jsonProjection
override from scalar descriptor classes such as PgTextDescriptor by providing
the default identity implementation on PostgresCodecDescriptor or reusing
identityJsonProjection. Preserve explicit overrides for array or custom
projection descriptors.

In `@packages/3-targets/3-targets/sqlite/test/typed-descriptor-flow.test-d.ts`:
- Around line 5-15: Update the AnySqliteCodecDescriptor import in the typed
descriptor flow test to use the public export from
../src/exports/codec-descriptor instead of the internal
../src/core/codec-descriptor module, while leaving the other imports unchanged.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro Plus

Run ID: 0f4d3ebb-9c7f-45e9-9ccd-9c48b289bccf

📥 Commits

Reviewing files that changed from the base of the PR and between bb29191 and 5640544.

⛔ Files ignored due to path filters (17)

pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
projects/codec-json-projections/slices/02-target-codec-descriptor-foundations/dispatches/01-postgres-descriptor-protocol-round-2.md is excluded by !projects/**
projects/codec-json-projections/slices/02-target-codec-descriptor-foundations/dispatches/01-postgres-descriptor-protocol.md is excluded by !projects/**
projects/codec-json-projections/slices/02-target-codec-descriptor-foundations/dispatches/02-sqlite-descriptor-protocol.md is excluded by !projects/**
projects/codec-json-projections/slices/02-target-codec-descriptor-foundations/dispatches/03-postgres-built-in-adoption.md is excluded by !projects/**
projects/codec-json-projections/slices/02-target-codec-descriptor-foundations/dispatches/04-sqlite-built-in-adoption.md is excluded by !projects/**
projects/codec-json-projections/slices/02-target-codec-descriptor-foundations/dispatches/05-postgres-extension-adoption.md is excluded by !projects/**
projects/codec-json-projections/slices/02-target-codec-descriptor-foundations/dispatches/06-postgres-adapter-composition-round-2.md is excluded by !projects/**
projects/codec-json-projections/slices/02-target-codec-descriptor-foundations/dispatches/06-postgres-adapter-composition.md is excluded by !projects/**
projects/codec-json-projections/slices/02-target-codec-descriptor-foundations/dispatches/07-sqlite-adapter-composition.md is excluded by !projects/**
projects/codec-json-projections/slices/02-target-codec-descriptor-foundations/dispatches/08-authoring-docs-and-upgrade-instructions-round-2.md is excluded by !projects/**
projects/codec-json-projections/slices/02-target-codec-descriptor-foundations/dispatches/08-authoring-docs-and-upgrade-instructions-round-3.md is excluded by !projects/**
projects/codec-json-projections/slices/02-target-codec-descriptor-foundations/dispatches/08-authoring-docs-and-upgrade-instructions.md is excluded by !projects/**
projects/codec-json-projections/slices/02-target-codec-descriptor-foundations/dispatches/09-preservation-audit-and-slice-gate.md is excluded by !projects/**
projects/codec-json-projections/slices/02-target-codec-descriptor-foundations/plan.md is excluded by !projects/**
projects/codec-json-projections/slices/02-target-codec-descriptor-foundations/spec.md is excluded by !projects/**
projects/codec-json-projections/trace.jsonl is excluded by !projects/**

📒 Files selected for processing (80)

docs/reference/codec-authoring-guide.md
packages/2-sql/2-authoring/contract-ts/src/contract-types.ts
packages/3-extensions/arktype-json/package.json
packages/3-extensions/arktype-json/src/core/arktype-json-codec.ts
packages/3-extensions/arktype-json/test/postgres-codec-descriptor-adoption.test-d.ts
packages/3-extensions/arktype-json/test/postgres-codec-descriptor-adoption.test.ts
packages/3-extensions/pgvector/package.json
packages/3-extensions/pgvector/src/core/codecs.ts
packages/3-extensions/pgvector/test/contract-declaration-portability.fixture.ts
packages/3-extensions/pgvector/test/contract-declaration-portability.test-d.ts
packages/3-extensions/pgvector/test/control-adapter-lower-parity.test.ts
packages/3-extensions/pgvector/test/operation-lowering.test.ts
packages/3-extensions/pgvector/test/operations.test.ts
packages/3-extensions/pgvector/test/postgres-codec-descriptor-adoption.test-d.ts
packages/3-extensions/pgvector/test/postgres-codec-descriptor-adoption.test.ts
packages/3-extensions/pgvector/test/rich-adapter.test.ts
packages/3-extensions/pgvector/test/sql-renderer.cast-policy.test.ts
packages/3-extensions/pgvector/test/typed-descriptor-flow.test-d.ts
packages/3-extensions/postgis/package.json
packages/3-extensions/postgis/src/core/codecs.ts
packages/3-extensions/postgis/test/postgres-codec-descriptor-adoption.test-d.ts
packages/3-extensions/postgis/test/postgres-codec-descriptor-adoption.test.ts
packages/3-targets/3-targets/postgres/README.md
packages/3-targets/3-targets/postgres/package.json
packages/3-targets/3-targets/postgres/src/core/codec-descriptor.ts
packages/3-targets/3-targets/postgres/src/core/codec-type-map.ts
packages/3-targets/3-targets/postgres/src/core/codecs.ts
packages/3-targets/3-targets/postgres/src/core/registry.ts
packages/3-targets/3-targets/postgres/src/exports/codec-descriptor.ts
packages/3-targets/3-targets/postgres/src/exports/codecs.ts
packages/3-targets/3-targets/postgres/test/postgres-built-in-codec-descriptors.test-d.ts
packages/3-targets/3-targets/postgres/test/postgres-built-in-codec-descriptors.test.ts
packages/3-targets/3-targets/postgres/test/postgres-codec-descriptor.test-d.ts
packages/3-targets/3-targets/postgres/test/postgres-codec-descriptor.test.ts
packages/3-targets/3-targets/postgres/test/typed-descriptor-flow.test-d.ts
packages/3-targets/3-targets/postgres/tsdown.config.ts
packages/3-targets/3-targets/sqlite/README.md
packages/3-targets/3-targets/sqlite/package.json
packages/3-targets/3-targets/sqlite/src/core/codec-descriptor.ts
packages/3-targets/3-targets/sqlite/src/core/codecs.ts
packages/3-targets/3-targets/sqlite/src/core/registry.ts
packages/3-targets/3-targets/sqlite/src/exports/codec-descriptor.ts
packages/3-targets/3-targets/sqlite/src/exports/codec-types.ts
packages/3-targets/3-targets/sqlite/src/exports/codecs.ts
packages/3-targets/3-targets/sqlite/test/sqlite-built-in-codec-descriptors.test-d.ts
packages/3-targets/3-targets/sqlite/test/sqlite-built-in-codec-descriptors.test.ts
packages/3-targets/3-targets/sqlite/test/sqlite-codec-descriptor.test-d.ts
packages/3-targets/3-targets/sqlite/test/sqlite-codec-descriptor.test.ts
packages/3-targets/3-targets/sqlite/test/typed-descriptor-flow.test-d.ts
packages/3-targets/3-targets/sqlite/tsdown.config.ts
packages/3-targets/6-adapters/postgres/README.md
packages/3-targets/6-adapters/postgres/src/core/adapter.ts
packages/3-targets/6-adapters/postgres/src/core/codec-lookup.ts
packages/3-targets/6-adapters/postgres/src/core/control-adapter.ts
packages/3-targets/6-adapters/postgres/src/core/sql-renderer.ts
packages/3-targets/6-adapters/postgres/src/core/types.ts
packages/3-targets/6-adapters/postgres/src/exports/control.ts
packages/3-targets/6-adapters/postgres/src/exports/runtime.ts
packages/3-targets/6-adapters/postgres/src/exports/types.ts
packages/3-targets/6-adapters/postgres/test/lower-to-execute-request.test.ts
packages/3-targets/6-adapters/postgres/test/migrations/data-transform.test.ts
packages/3-targets/6-adapters/postgres/test/postgres-adapter-options.test-d.ts
packages/3-targets/6-adapters/postgres/test/postgres-codec-registry-composition.test.ts
packages/3-targets/6-adapters/postgres/test/raw-expr-lowering.test.ts
packages/3-targets/6-adapters/postgres/test/sql-renderer-namespace-qualification.test.ts
packages/3-targets/6-adapters/postgres/test/sql-renderer.cast-policy.test.ts
packages/3-targets/6-adapters/sqlite/README.md
packages/3-targets/6-adapters/sqlite/src/core/adapter.ts
packages/3-targets/6-adapters/sqlite/src/core/codec-lookup.ts
packages/3-targets/6-adapters/sqlite/src/core/control-adapter.ts
packages/3-targets/6-adapters/sqlite/src/core/runtime-adapter.ts
packages/3-targets/6-adapters/sqlite/src/core/types.ts
packages/3-targets/6-adapters/sqlite/src/exports/adapter.ts
packages/3-targets/6-adapters/sqlite/src/exports/control.ts
packages/3-targets/6-adapters/sqlite/src/exports/types.ts
packages/3-targets/6-adapters/sqlite/test/lower-to-execute-request.test.ts
packages/3-targets/6-adapters/sqlite/test/sqlite-adapter-options.test-d.ts
packages/3-targets/6-adapters/sqlite/test/sqlite-codec-registry-composition.test.ts
packages/3-targets/6-adapters/sqlite/test/verification-checks-lowering.test.ts
skills/extension-author/prisma-next-extension-upgrade/upgrades/0.16-to-0.17/instructions.md

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

SqliteControlAdapter takes a SqliteCodecRegistry, so the structured-error DDL test composes its stub over createSqliteBuiltinCodecLookup() and overrides only get(). The DDL default-rendering path reads codecs through get() alone, so the exercised behavior is unchanged. Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

tensordreams · 2026-07-27T12:31:26Z

Triaged both CodeRabbit nitpicks from this review. Verified each against the current tree (post-rebase); declining both, with reasons.

1. AnySqliteCodecDescriptor import in sqlite/test/typed-descriptor-flow.test-d.ts — not changing.

The factual half checks out: the type is re-exported from src/exports/codec-descriptor, and sqlite-codec-descriptor.test.ts / .test-d.ts do import from there. But the repo convention runs the other way. docs/reference/test-import-patterns.md, under "The exports/ Folder", says plainly: "Tests should import from source files directly, not from the exports/ folder", with the ../src/exports/… form marked WRONG. .agents/rules/test-import-patterns.mdc says the same. Applying the suggestion would move this file from the documented pattern to the documented anti-pattern.

The cited precedent is also a partial sample — within this package 3 of 5 descriptor tests import the type from core and only 2 from exports, so core is the majority. And this file is a constructive type test of the internal descriptor record layer: it already imports codecDescriptors from ../src/core/codecs, a symbol not on the exports surface at all, so routing only the type through exports/ would split one file's imports across two boundaries for nothing. Its stated mirror, postgres/test/typed-descriptor-flow.test-d.ts, imports AnyPostgresCodecDescriptor from ../src/core/codec-descriptor identically — changing SQLite alone would desynchronise the pair. Where the exports-surface boundary genuinely wants asserting, sqlite-codec-descriptor.test.ts already covers it.

2. Identity jsonProjection repetition in postgres/src/core/codecs.ts — deliberate, not boilerplate.

PostgresCodecDescriptor declares protected abstract jsonProjection(...), and the abstractness is the mechanism — a default identity would silently satisfy the protocol for every future descriptor. This exact temptation is named and rejected in the slice's design record: "Identity projection looks tempting as an implicit default. → Keep scalar projection mandatory; built-ins and adapters declare identity explicitly during this behavior-preserving slice. → An omission must not silently claim losslessness." The authoring guide states it to users too (docs/reference/codec-authoring-guide.md): "Identity is an explicit, behavior-preserving declaration during the 0.17 transition, not an implicit default", and "A required identity jsonProjection therefore means 'preserve today's SQL JSON output while declaring the target boundary', not 'this representation is canonical or lossless'."

The published 0.16→0.17 upgrade instructions bind downstream extension authors to the same contract ("add protected override jsonProjection(...). Use return expression for the 0.17 behavior-preserving migration…"). Adding a default would make the framework's own built-ins stop doing what extension authors are told to do, and would let the later lossless-JSON hard cut silently inherit identity for any codec nobody revisited. CodeRabbit hedged this one itself ("If the intent is a per-codec authoring decision, keeping it explicit is fine") and graded it Trivial / Low value — the intent is indeed per-codec.

The codec-ref helpers in the target descriptor tests hand-rolled the conditional property spread for the optional `typeParams` and `many` fields. `ifDefined` from `@prisma-next/utils/defined` expresses the same thing directly, per .agents/rules/use-if-defined.mdc. Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/reference/codec-authoring-guide.md`:
- Around line 110-116: Add the missing imports in the Case 2 and Case 3 examples
for the PostgreSQL descriptor value used by PgVectorDescriptor and the
ProjectionExpr type used by nativeType/jsonProjection signatures. Keep the
examples otherwise unchanged so both code blocks are copyable and
type-checkable.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro Plus

Run ID: 1e8a834b-dce2-40bd-8f66-0c40eaec098a

📥 Commits

Reviewing files that changed from the base of the PR and between 5640544 and 310318b.

📒 Files selected for processing (11)

docs/reference/codec-authoring-guide.md
packages/2-sql/2-authoring/contract-ts/src/contract-types.ts
packages/3-extensions/arktype-json/package.json
packages/3-extensions/arktype-json/src/core/arktype-json-codec.ts
packages/3-extensions/arktype-json/test/postgres-codec-descriptor-adoption.test-d.ts
packages/3-extensions/arktype-json/test/postgres-codec-descriptor-adoption.test.ts
packages/3-extensions/pgvector/package.json
packages/3-extensions/pgvector/src/core/codecs.ts
packages/3-extensions/pgvector/test/contract-declaration-portability.fixture.ts
packages/3-extensions/pgvector/test/contract-declaration-portability.test-d.ts
packages/3-extensions/pgvector/test/control-adapter-lower-parity.test.ts

🚧 Files skipped from review as they are similar to previous changes (9)

packages/3-extensions/pgvector/test/contract-declaration-portability.fixture.ts
packages/3-extensions/pgvector/test/control-adapter-lower-parity.test.ts
packages/3-extensions/arktype-json/test/postgres-codec-descriptor-adoption.test.ts
packages/3-extensions/arktype-json/package.json
packages/3-extensions/arktype-json/test/postgres-codec-descriptor-adoption.test-d.ts
packages/2-sql/2-authoring/contract-ts/src/contract-types.ts
packages/3-extensions/pgvector/src/core/codecs.ts
packages/3-extensions/pgvector/package.json
packages/3-extensions/arktype-json/src/core/arktype-json-codec.ts

The case-study blocks are descriptor-shape excerpts, not complete files: Case 1 carries the full framework import block, Cases 2 and 3 list only what each adds, and all three elide the pack own internals. Say so, so the blocks are not read as copyable modules. Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

tensordreams requested a review from a team as a code owner July 24, 2026 06:55

coderabbitai Bot reviewed Jul 24, 2026

View reviewed changes

aqrln reviewed Jul 27, 2026

View reviewed changes

Comment thread packages/3-targets/3-targets/postgres/src/core/codecs.ts

aqrln reviewed Jul 27, 2026

View reviewed changes

Comment thread packages/3-targets/3-targets/sqlite/src/exports/codec-types.ts

aqrln reviewed Jul 27, 2026

View reviewed changes

Comment thread packages/3-targets/6-adapters/postgres/src/exports/control.ts

tensordreams added 22 commits July 27, 2026 14:02

TML-3061: specify target codec descriptor foundations

524de2f

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: dispatch PostgreSQL descriptor protocol

e7cbb55

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

feat(postgres): add target codec descriptor protocol

22e8cce

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: re-dispatch PostgreSQL descriptor protocol

aae794f

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

fix(postgres): tighten codec descriptor protocol

3dccb91

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: record PostgreSQL descriptor protocol dispatch

510f6a0

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: dispatch SQLite descriptor protocol

91ebcd7

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

feat(sqlite): add target codec descriptor protocol

7c23104

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: record SQLite descriptor protocol dispatch

2dd8638

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: dispatch PostgreSQL built-in adoption

8879426

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

feat(postgres): adopt built-in codec descriptors

1a72ff5

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: record PostgreSQL built-in adoption dispatch

d003ef1

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: dispatch SQLite built-in adoption

122ec75

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

feat(sqlite): adopt built-in codec descriptors

a5c8eb4

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: record SQLite built-in adoption dispatch

bce9f7c

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: sequence extension adoption before validation

60a21bd

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: dispatch PostgreSQL extension adoption

e398f53

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

feat(extensions): adopt PostgreSQL codec descriptors

1f7ed29

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: record PostgreSQL extension adoption dispatch

948d5e0

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: dispatch PostgreSQL adapter composition

13f31bb

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

feat(postgres): compose target codec registries

678099a

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: correct PostgreSQL registry injection

99d5c7c

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

tensordreams added 18 commits July 27, 2026 14:04

fix(postgres): make codec registry injection coherent

27ee7c2

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: record PostgreSQL adapter composition dispatch

ec7df34

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: dispatch SQLite adapter composition

868c383

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

feat(sqlite): compose target codec registries

8efcb47

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: record SQLite adapter composition dispatch

d09d775

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: dispatch authoring docs and upgrade instructions

ccfe744

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: repair extension replay fixtures

656a33e

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: supply pgvector fixture dimensions

7ed1c12

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: document target codec descriptor authoring

bc8618b

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: correct codec authoring examples

34cbd5c

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: correct descriptor examples and dimensions

bec2a73

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: record authoring docs dispatch

a432fd6

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: dispatch preservation audit

56fb506

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: adapt SQLite composition to extensions rename

2b31f0e

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: align PostgreSQL emitted descriptor tests

40aa64e

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: make extension codec types declaration-portable

a1a9c03

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

TML-3061: record preservation audit dispatch

80eb633

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

tensordreams force-pushed the tml-3061-target-codec-descriptor-foundations branch from 5640544 to 6690e02 Compare July 27, 2026 12:17

coderabbitai Bot reviewed Jul 27, 2026

View reviewed changes

Comment thread docs/reference/codec-authoring-guide.md

aqrln approved these changes Jul 27, 2026

View reviewed changes

aqrln added this pull request to the merge queue Jul 27, 2026

Merged via the queue into main with commit e0e739c Jul 27, 2026
22 checks passed

aqrln deleted the tml-3061-target-codec-descriptor-foundations branch July 27, 2026 13:41

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

TML-3061: PostgreSQL and SQLite codec descriptor protocols#1051

TML-3061: PostgreSQL and SQLite codec descriptor protocols#1051
aqrln merged 42 commits into
mainfrom
tml-3061-target-codec-descriptor-foundations

tensordreams commented Jul 24, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 24, 2026 •

edited

Loading

Walkthrough

Changes

❌ Failed checks (1 warning)

Uh oh!

pkg-pr-new Bot commented Jul 24, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 24, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tensordreams commented Jul 27, 2026

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

tensordreams commented Jul 24, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Linked issue

At a glance

Decision

Reviewer notes

How it fits together

Behavior changes & evidence

Compatibility / migration / risk

Testing performed

Skill update

Follow-ups

Alternatives considered

Checklist

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

❌ Failed checks (1 warning)

Uh oh!

pkg-pr-new Bot commented Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

size-limit report 📦

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tensordreams commented Jul 27, 2026

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

tensordreams commented Jul 24, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 24, 2026 •

edited

Loading

pkg-pr-new Bot commented Jul 24, 2026 •

edited

Loading

github-actions Bot commented Jul 24, 2026 •

edited

Loading