@prisma-next/target-postgres 0.5.0-dev.6 → 0.5.0-dev.61

package/src/core/descriptor-meta.ts

@@ -1,5 +1,5 @@
+import type { CodecTypes } from '../exports/codec-types';
 import { postgresAuthoringFieldPresets, postgresAuthoringTypes } from './authoring';
-import type { CodecTypes } from './codecs';
 
 const postgresTargetDescriptorMetaBase = {
   kind: 'target',

package/src/core/migrations/operations/data-transform.ts

@@ -11,7 +11,7 @@
  *   override get operations() {
  *     return [
  *       this.dataTransform(endContract, 'backfill emails', {
- *         check: () => db.users.count().where(({ email }) => email.isNull()),
+ *         check: () => db.users.select('id').where(({ email }) => email.isNull()).limit(1),
  *         run:   () => db.users.update({ email: '' }).where(({ email }) => email.isNull()),
  *       }),
  *     ];
@@ -23,20 +23,49 @@
  * invokes each one, asserts that its `meta.storageHash` matches the
  * `contract` it was handed (→ `PN-MIG-2005` on mismatch), and lowers the
  * plan via the supplied control adapter to a serialized `{sql, params}`
- * payload for `ops.json`. The free factory remains usable standalone
- * (tests, ad-hoc tooling, non-class contexts) by passing the adapter
- * explicitly as the fourth argument.
+ * payload.
+ *
+ * The factory then lowers the data transform to the unified migration-op
+ * shape `{ precheck, execute, postcheck }`. The user's `check` plan is
+ * wrapped twice with opposite truth values:
+ *
+ * - precheck `SELECT EXISTS (<check>) AS ok` asserts there is work to do
+ *   (precheck is short-circuited by the runner's pre-satisfied-skip path
+ *   when nothing remains to backfill).
+ * - postcheck `SELECT NOT EXISTS (<check>) AS ok` asserts the work is
+ *   complete after the run steps execute.
+ *
+ * The `check` plan is therefore expected to be a **rowset query whose
+ * presence of any row signals "work remains"** — typically `select('id')
+ * .where(<violation predicate>).limit(1)`. Scalar/aggregate shapes
+ * (`count(*)`, `bool_and(...)`) do not work under this contract: they
+ * always return exactly one row, so `EXISTS` is always true and
+ * `NOT EXISTS` is always false. (This is the same row-presence contract
+ * the pre-unification runner relied on; the wrapping is just lifting it
+ * into SQL.)
+ *
+ * Each `run` plan becomes an execute step. Because the `Step.params`
+ * field threads through `driver.query(sql, params)`, the user's bound
+ * values flow through the driver's parameter binder rather than being
+ * inlined into the SQL text.
+ *
+ * The free factory remains usable standalone (tests, ad-hoc tooling,
+ * non-class contexts) by passing the adapter explicitly as the fourth
+ * argument.
  */
 
 import type { Contract } from '@prisma-next/contract/types';
 import { errorDataTransformContractMismatch } from '@prisma-next/errors/migration';
-import type { SqlControlAdapter } from '@prisma-next/family-sql/control-adapter';
 import type {
-  DataTransformOperation,
-  SerializedQueryPlan,
-} from '@prisma-next/framework-components/control';
+  SqlMigrationPlanOperation,
+  SqlMigrationPlanOperationStep,
+} from '@prisma-next/family-sql/control';
+import type { SqlControlAdapter } from '@prisma-next/family-sql/control-adapter';
+import type { SerializedQueryPlan } from '@prisma-next/framework-components/control';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import type { SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';
+import { ifDefined } from '@prisma-next/utils/defined';
+import type { PostgresPlanTargetDetails } from '../planner-target-details';
 
 interface Buildable<R = unknown> {
   build(): SqlQueryPlan<R>;
@@ -49,36 +78,72 @@ interface Buildable<R = unknown> {
 export type DataTransformClosure = () => SqlQueryPlan | Buildable;
 
 export interface DataTransformOptions {
-  /** Optional pre-flight query. `undefined` means "no check". */
+  /**
+   * Optional opt-in routing identity. Presence opts the transform into
+   * invariant-aware routing; absence means it is path-dependent and
+   * not referenceable from refs.
+   */
+  readonly invariantId?: string;
+  /**
+   * Optional pre-flight query. `undefined` means "no check". When
+   * supplied, the closure must return a **rowset query** whose
+   * presence of any row signals "violations remain". Conventional
+   * shape: `db.<table>.select('id').where(<violation>).limit(1)`.
+   * Scalar/aggregate shapes do not satisfy this contract.
+   */
   readonly check?: DataTransformClosure;
   /** One or more mutation queries to execute. */
   readonly run: DataTransformClosure | readonly DataTransformClosure[];
 }
 
-/**
- * Concrete Postgres flavor of `DataTransformOperation`, re-exported so the
- * `PostgresMigration.dataTransform` instance method can name it without
- * leaking the framework-components symbol into call sites.
- */
-export type PostgresDataTransformOperation = DataTransformOperation;
-
 export function dataTransform<TContract extends Contract<SqlStorage>>(
   contract: TContract,
   name: string,
   options: DataTransformOptions,
   adapter: SqlControlAdapter<'postgres'>,
-): DataTransformOperation {
+): SqlMigrationPlanOperation<PostgresPlanTargetDetails> {
   const runClosures: readonly DataTransformClosure[] = Array.isArray(options.run)
     ? options.run
     : [options.run as DataTransformClosure];
+
+  const checkPlan = options.check ? invokeAndLower(options.check, contract, adapter, name) : null;
+  const runPlans = runClosures.map((closure) => invokeAndLower(closure, contract, adapter, name));
+
+  const precheck: readonly SqlMigrationPlanOperationStep[] = checkPlan
+    ? [
+        {
+          description: `Check ${name} has work to do`,
+          sql: `SELECT EXISTS (${checkPlan.sql}) AS ok`,
+          params: checkPlan.params,
+        },
+      ]
+    : [];
+
+  const execute: readonly SqlMigrationPlanOperationStep[] = runPlans.map((plan) => ({
+    description: `Run ${name}`,
+    sql: plan.sql,
+    params: plan.params,
+  }));
+
+  const postcheck: readonly SqlMigrationPlanOperationStep[] = checkPlan
+    ? [
+        {
+          description: `Verify ${name} resolved all violations`,
+          sql: `SELECT NOT EXISTS (${checkPlan.sql}) AS ok`,
+          params: checkPlan.params,
+        },
+      ]
+    : [];
+
   return {
     id: `data_migration.${name}`,
     label: `Data transform: ${name}`,
     operationClass: 'data',
-    name,
-    source: 'migration.ts',
-    check: options.check ? invokeAndLower(options.check, contract, adapter, name) : null,
-    run: runClosures.map((closure) => invokeAndLower(closure, contract, adapter, name)),
+    ...ifDefined('invariantId', options.invariantId),
+    target: { id: 'postgres' },
+    precheck,
+    execute,
+    postcheck,
   };
 }
 

package/src/core/migrations/planner-produced-postgres-migration.ts

@@ -60,7 +60,6 @@ export class TypeScriptRenderablePostgresMigration
     return renderCallsToTypeScript(this.#calls, {
       from: this.#meta.from,
       to: this.#meta.to,
-      ...ifDefined('kind', this.#meta.kind),
       ...ifDefined('labels', this.#meta.labels),
     });
   }

package/src/core/migrations/planner.ts

@@ -1,3 +1,4 @@
+import type { Contract } from '@prisma-next/contract/types';
 import type {
   MigrationOperationPolicy,
   SqlMigrationPlannerPlanOptions,
@@ -83,20 +84,25 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
     readonly contract: unknown;
     readonly schema: unknown;
     readonly policy: MigrationOperationPolicy;
-    readonly fromHash?: string;
     /**
      * The "from" contract (state the planner assumes the database starts
-     * at). Only `migration plan` supplies this; `db update` / `db init`
-     * reconcile against the live schema with no old contract. When present
-     * alongside the `'data'` operation class, strategies that need from/to
-     * column shape comparisons (unsafe type change, nullability tightening)
-     * activate.
+     * at), or `null` for reconciliation flows. Only `migration plan` ever
+     * supplies a non-null value; `db update` / `db init` reconcile against
+     * the live schema and pass `null`. When present alongside the
+     * `'data'` operation class, strategies that need from/to column-shape
+     * comparisons (unsafe type change, nullability tightening) activate.
+     *
+     * Typed as the framework `Contract | null` to satisfy the
+     * `MigrationPlanner` interface contract; `planSql` narrows to the SQL
+     * shape via `SqlMigrationPlannerPlanOptions`. Used to populate
+     * `describe().from` on the produced plan as
+     * `fromContract?.storage.storageHash ?? null`.
      */
-    readonly fromContract?: unknown;
+    readonly fromContract: Contract | null;
     readonly schemaName?: string;
     readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
   }): PostgresPlanResult {
-    return this.planSql(options as SqlMigrationPlannerPlanOptions, options.fromHash ?? '');
+    return this.planSql(options as SqlMigrationPlannerPlanOptions);
   }
 
   emptyMigration(context: MigrationScaffoldContext): MigrationPlanWithAuthoringSurface {
@@ -106,7 +112,7 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
     });
   }
 
-  private planSql(options: SqlMigrationPlannerPlanOptions, fromHash: string): PostgresPlanResult {
+  private planSql(options: SqlMigrationPlannerPlanOptions): PostgresPlanResult {
     const schemaName = options.schemaName ?? this.config.defaultSchema;
     const policyResult = this.ensureAdditivePolicy(options.policy);
     if (policyResult) {
@@ -125,7 +131,7 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
       // from/to comparisons (unsafe type change, nullable tightening) are
       // inapplicable there — reconciliation falls through to
       // `mapIssueToCall`'s direct destructive handlers.
-      fromContract: options.fromContract ?? null,
+      fromContract: options.fromContract,
       schemaName,
       codecHooks,
       storageTypes,
@@ -142,7 +148,7 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
     return Object.freeze({
       kind: 'success' as const,
       plan: new TypeScriptRenderablePostgresMigration(result.value.calls, {
-        from: fromHash,
+        from: options.fromContract?.storage.storageHash ?? null,
         to: options.contract.storage.storageHash,
       }),
     });

package/src/core/migrations/postgres-migration.ts

@@ -1,14 +1,11 @@
 import type { Contract } from '@prisma-next/contract/types';
+import type { SqlMigrationPlanOperation } from '@prisma-next/family-sql/control';
 import type { SqlControlAdapter } from '@prisma-next/family-sql/control-adapter';
 import { Migration as SqlMigration } from '@prisma-next/family-sql/migration';
 import type { ControlStack } from '@prisma-next/framework-components/control';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import { errorPostgresMigrationStackMissing } from '../errors';
-import {
-  type DataTransformOptions,
-  dataTransform,
-  type PostgresDataTransformOperation,
-} from './operations/data-transform';
+import { type DataTransformOptions, dataTransform } from './operations/data-transform';
 import type { PostgresPlanTargetDetails } from './planner-target-details';
 
 /**
@@ -64,7 +61,7 @@ export abstract class PostgresMigration extends SqlMigration<
     contract: TContract,
     name: string,
     options: DataTransformOptions,
-  ): PostgresDataTransformOperation {
+  ): SqlMigrationPlanOperation<PostgresPlanTargetDetails> {
     if (!this.controlAdapter) {
       throw errorPostgresMigrationStackMissing();
     }

package/src/core/migrations/render-typescript.ts

@@ -14,9 +14,8 @@ import { type ImportRequirement, jsonToTsSource, renderImports } from '@prisma-n
 import type { PostgresOpFactoryCall } from './op-factory-call';
 
 export interface RenderMigrationMeta {
-  readonly from: string;
+  readonly from: string | null;
   readonly to: string;
-  readonly kind?: string;
   readonly labels?: readonly string[];
 }
 
@@ -84,9 +83,6 @@ function buildDescribeMethod(meta: RenderMigrationMeta): string {
   lines.push('    return {');
   lines.push(`      from: ${JSON.stringify(meta.from)},`);
   lines.push(`      to: ${JSON.stringify(meta.to)},`);
-  if (meta.kind) {
-    lines.push(`      kind: ${JSON.stringify(meta.kind)},`);
-  }
   if (meta.labels && meta.labels.length > 0) {
     lines.push(`      labels: ${jsonToTsSource(meta.labels)},`);
   }

package/src/core/migrations/runner.ts

@@ -12,8 +12,6 @@ import type {
 } from '@prisma-next/family-sql/control';
 import { runnerFailure, runnerSuccess } from '@prisma-next/family-sql/control';
 import { verifySqlSchema } from '@prisma-next/family-sql/schema-verify';
-import { readMarker } from '@prisma-next/family-sql/verify';
-import type { DataTransformOperation } from '@prisma-next/framework-components/control';
 import { SqlQueryError } from '@prisma-next/sql-errors';
 import { ifDefined } from '@prisma-next/utils/defined';
 import type { Result } from '@prisma-next/utils/result';
@@ -23,7 +21,7 @@ import { normalizeSchemaNativeType } from '../native-type-normalizer';
 import type { PostgresPlanTargetDetails } from './planner-target-details';
 import {
   buildLedgerInsertStatement,
-  buildWriteMarkerStatements,
+  buildMergeMarkerStatements,
   ensureLedgerTableStatement,
   ensureMarkerTableStatement,
   ensurePrismaContractSchemaStatement,
@@ -45,18 +43,6 @@ const DEFAULT_CONFIG: RunnerConfig = {
 
 const LOCK_DOMAIN = 'prisma_next.contract.marker';
 
-function isDataTransformOperation(op: unknown): op is DataTransformOperation {
-  return (
-    typeof op === 'object' &&
-    op !== null &&
-    'operationClass' in op &&
-    (op as { operationClass: string }).operationClass === 'data' &&
-    'name' in op &&
-    'check' in op &&
-    'run' in op
-  );
-}
-
 /**
  * Deep clones and freezes a record object to prevent mutation.
  * Recursively clones nested objects and arrays to ensure complete isolation.
@@ -120,7 +106,7 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
     try {
       await this.acquireLock(driver, lockKey);
       await this.ensureControlTables(driver);
-      const existingMarker = await readMarker(driver);
+      const existingMarker = await this.family.readMarker({ driver });
 
       // Validate plan origin matches existing marker (needs marker from DB)
       const markerCheck = this.ensureMarkerCompatibility(existingMarker, options.plan);
@@ -128,9 +114,14 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
         return markerCheck;
       }
 
-      // db update (origin: null) always applies; migration-apply (origin set) skips if marker matches.
+      // db update (origin: null) always applies; migration-apply (origin set,
+      // origin !== destination) skips if marker already matches destination.
+      // Self-edges (origin === destination) intentionally bypass the skip:
+      // the migration is data-only, and the data transform's own check
+      // decides whether `run` fires.
       const markerAtDestination = this.markerMatchesDestination(existingMarker, options.plan);
-      const skipOperations = markerAtDestination && options.plan.origin != null;
+      const isSelfEdge = options.plan.origin?.storageHash === options.plan.destination.storageHash;
+      const skipOperations = markerAtDestination && options.plan.origin != null && !isSelfEdge;
       let applyValue: ApplyPlanSuccessValue;
 
       if (skipOperations) {
@@ -170,9 +161,34 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
         });
       }
 
-      // Record marker and ledger entries
-      await this.upsertMarker(driver, options, existingMarker);
-      await this.recordLedgerEntry(driver, options, existingMarker, applyValue.executedOperations);
+      // Self-edge no-op detection: a self-edge migration whose ops all
+      // self-skipped (every op pre-satisfied) and that brings no new
+      // invariants produced no observable change. Skip the marker +
+      // ledger writes so an idempotent re-apply of a self-edge data
+      // transform doesn't churn updatedAt or pile up empty ledger
+      // entries. With data transforms now flowing through the unified
+      // op loop, a pre-satisfied DT lands in the
+      // `postcheckAlreadySatisfied` skip path which does not increment
+      // `operationsExecuted`, so the check below correctly distinguishes
+      // "every op self-skipped" from "the plan had ops that ran". `db
+      // update` no-ops still write a ledger entry as audit trail.
+      const incomingInvariants = options.plan.providedInvariants ?? [];
+      const existingInvariants = new Set(existingMarker?.invariants ?? []);
+      const incomingIsSubsetOfExisting = incomingInvariants.every((id) =>
+        existingInvariants.has(id),
+      );
+      const isSelfEdgeNoOp =
+        isSelfEdge && applyValue.operationsExecuted === 0 && incomingIsSubsetOfExisting;
+
+      if (!isSelfEdgeNoOp) {
+        await this.upsertMarker(driver, options, existingMarker);
+        await this.recordLedgerEntry(
+          driver,
+          options,
+          existingMarker,
+          applyValue.executedOperations,
+        );
+      }
 
       await this.commitTransaction(driver);
       committed = true;
@@ -201,19 +217,6 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
     for (const operation of options.plan.operations) {
       options.callbacks?.onOperationStart?.(operation);
       try {
-        // Data transform operations have a different execution lifecycle
-        if (operation.operationClass === 'data' && isDataTransformOperation(operation)) {
-          const dtResult = await this.executeDataTransform(driver, operation, {
-            runIdempotency,
-          });
-          if (!dtResult.ok) {
-            return dtResult;
-          }
-          executedOperations.push(operation);
-          operationsExecuted += 1;
-          continue;
-        }
-
         // Idempotency probe: only run if both postchecks and idempotency checks are enabled
         if (runPostchecks && runIdempotency) {
           const postcheckAlreadySatisfied = await this.expectationsAreSatisfied(
@@ -266,80 +269,6 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
     return ok({ operationsExecuted, executedOperations });
   }
 
-  /**
-   * Executes a data transform operation with the check → (skip or run) → check lifecycle.
-   *
-   * 1. If check is a query AST: render to SQL, execute. Empty result = already applied (skip).
-   * 2. If check is `true`: always skip. If `false`: always run.
-   * 3. Execute run ASTs (rendered to SQL) sequentially.
-   * 4. Re-execute check as post-run validation. If violations remain, fail.
-   */
-  private async executeDataTransform(
-    driver: SqlMigrationRunnerExecuteOptions<PostgresPlanTargetDetails>['driver'],
-    op: DataTransformOperation,
-    options: { runIdempotency: boolean },
-  ): Promise<Result<void, SqlMigrationRunnerFailure>> {
-    // Step 1: Check (skip guard)
-    if (op.check === true) {
-      // Always skip, regardless of idempotency setting
-      return okVoid();
-    }
-    if (options.runIdempotency && op.check !== null && op.check !== false) {
-      const checkResult = await driver.query(op.check.sql, op.check.params);
-      if (checkResult.rows.length === 0) {
-        // No violations — already applied, skip
-        return okVoid();
-      }
-    }
-
-    // Step 2: Execute run steps
-    if (op.run) {
-      for (const plan of op.run) {
-        try {
-          await driver.query(plan.sql, plan.params);
-        } catch (error: unknown) {
-          if (SqlQueryError.is(error)) {
-            return runnerFailure(
-              'EXECUTION_FAILED',
-              `Data transform "${op.name}" failed: ${error.message}`,
-              {
-                why: error.message,
-                meta: {
-                  operationId: op.id,
-                  dataTransformName: op.name,
-                  sql: plan.sql,
-                  sqlState: error.sqlState,
-                },
-              },
-            );
-          }
-          throw error;
-        }
-      }
-    }
-
-    // Step 3: Post-run validation (check again)
-    if (op.check !== null && op.check !== false) {
-      const checkResult = await driver.query(op.check.sql, op.check.params);
-      if (checkResult.rows.length > 0) {
-        return runnerFailure(
-          'POSTCHECK_FAILED',
-          `Data transform "${op.name}" did not resolve all violations (${checkResult.rows.length} remaining)`,
-          {
-            why: `After executing the data transform, the check query still returns ${checkResult.rows.length} violation(s).`,
-            meta: {
-              operationId: op.id,
-              dataTransformName: op.name,
-              remainingViolations: checkResult.rows.length,
-            },
-          },
-        );
-      }
-    }
-
-    return okVoid();
-  }
-
   private async ensureControlTables(
     driver: SqlMigrationRunnerExecuteOptions<PostgresPlanTargetDetails>['driver'],
   ): Promise<void> {
@@ -355,7 +284,7 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
     phase: 'precheck' | 'postcheck',
   ): Promise<Result<void, SqlMigrationRunnerFailure>> {
     for (const step of steps) {
-      const result = await driver.query(step.sql);
+      const result = await driver.query(step.sql, step.params ?? []);
       if (!this.stepResultIsTrue(result.rows)) {
         const code = phase === 'precheck' ? 'PRECHECK_FAILED' : 'POSTCHECK_FAILED';
         return runnerFailure(
@@ -381,7 +310,7 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
   ): Promise<Result<void, SqlMigrationRunnerFailure>> {
     for (const step of steps) {
       try {
-        await driver.query(step.sql);
+        await driver.query(step.sql, step.params ?? []);
       } catch (error: unknown) {
         // Catch SqlQueryError and include normalized metadata
         if (SqlQueryError.is(error)) {
@@ -445,7 +374,7 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
       return false;
     }
     for (const step of steps) {
-      const result = await driver.query(step.sql);
+      const result = await driver.query(step.sql, step.params ?? []);
       if (!this.stepResultIsTrue(result.rows)) {
         return false;
       }
@@ -617,7 +546,8 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
     options: SqlMigrationRunnerExecuteOptions<PostgresPlanTargetDetails>,
     existingMarker: ContractMarkerRecord | null,
   ): Promise<void> {
-    const writeStatements = buildWriteMarkerStatements({
+    const incomingInvariants = options.plan.providedInvariants ?? [];
+    const writeStatements = buildMergeMarkerStatements({
       storageHash: options.plan.destination.storageHash,
       profileHash:
         options.plan.destination.profileHash ??
@@ -626,6 +556,7 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
       contractJson: options.destinationContract,
       canonicalVersion: null,
       meta: {},
+      invariants: incomingInvariants,
     });
     const statement = existingMarker ? writeStatements.update : writeStatements.insert;
     await this.executeStatement(driver, statement);

package/src/core/migrations/statement-builders.ts

@@ -17,7 +17,8 @@ export const ensureMarkerTableStatement: SqlStatement = {
     canonical_version int,
     updated_at timestamptz not null default now(),
     app_tag text,
-    meta jsonb not null default '{}'
+    meta jsonb not null default '{}',
+    invariants text[] not null default '{}'
   )`,
   params: [],
 };
@@ -37,16 +38,23 @@ export const ensureLedgerTableStatement: SqlStatement = {
   params: [],
 };
 
-export interface WriteMarkerInput {
+export interface MergeMarkerInput {
   readonly storageHash: string;
   readonly profileHash: string;
   readonly contractJson?: unknown;
   readonly canonicalVersion?: number | null;
   readonly appTag?: string | null;
   readonly meta?: Record<string, unknown>;
+  /**
+   * Invariants to merge into `marker.invariants`. INSERT writes them as
+   * the initial value (callers are expected to pass a sorted, deduped
+   * array). UPDATE merges them with the existing column server-side via
+   * a single atomic SQL expression.
+   */
+  readonly invariants: readonly string[];
 }
 
-export function buildWriteMarkerStatements(input: WriteMarkerInput): {
+export function buildMergeMarkerStatements(input: MergeMarkerInput): {
   readonly insert: SqlStatement;
   readonly update: SqlStatement;
 } {
@@ -58,6 +66,7 @@ export function buildWriteMarkerStatements(input: WriteMarkerInput): {
     input.canonicalVersion ?? null,
     input.appTag ?? null,
     jsonParam(input.meta ?? {}),
+    input.invariants,
   ];
 
   return {
@@ -70,7 +79,8 @@ export function buildWriteMarkerStatements(input: WriteMarkerInput): {
         canonical_version,
         updated_at,
         app_tag,
-        meta
+        meta,
+        invariants
       ) values (
         $1,
         $2,
@@ -79,11 +89,16 @@ export function buildWriteMarkerStatements(input: WriteMarkerInput): {
         $5,
         now(),
         $6,
-        $7::jsonb
+        $7::jsonb,
+        $8::text[]
       )`,
       params,
     },
     update: {
+      // `invariants = array(select distinct unnest(invariants || $8::text[]) order by 1)`
+      // reads the current column value under the UPDATE's row lock, unions
+      // with the incoming array, dedupes, and sorts ascending — single
+      // statement, atomic, no read-then-write window.
       sql: `update prisma_contract.marker set
         core_hash = $2,
         profile_hash = $3,
@@ -91,7 +106,8 @@ export function buildWriteMarkerStatements(input: WriteMarkerInput): {
         canonical_version = $5,
         updated_at = now(),
         app_tag = $6,
-        meta = $7::jsonb
+        meta = $7::jsonb,
+        invariants = array(select distinct unnest(invariants || $8::text[]) order by 1)
       where id = $1`,
       params,
     },

package/src/core/registry.ts

@@ -0,0 +1,11 @@
+import { buildCodecDescriptorRegistry } from '@prisma-next/sql-relational-core/codec-descriptor-registry';
+import type { CodecDescriptorRegistry } from '@prisma-next/sql-relational-core/query-lane-context';
+import { codecDescriptors } from './codecs';
+
+/**
+ * Registry of every codec descriptor shipped by `@prisma-next/target-postgres`.
+ *
+ * Public consumer surface for the postgres codec set: the postgres adapter and any other consumer that needs to enumerate or look up a postgres codec by id consumes this rather than the raw descriptor array. See ADR 208.
+ */
+export const postgresCodecRegistry: CodecDescriptorRegistry =
+  buildCodecDescriptorRegistry(codecDescriptors);

package/src/exports/codec-types.ts

@@ -1,26 +1,17 @@
 /**
  * Codec type definitions for the Postgres target.
  *
- * This file exports type-only definitions for codec input/output types.
- * These types are imported by generated `contract.d.ts` files for compile-time
- * type inference.
+ * This file is the public origin of `CodecTypes`. The `Resolve<...>` materialisation happens here (rather than in `core/codec-type-map.ts`) so the tsdown DTS bundler resolves consumer-side `.d.mts` references via this public entry point rather than a hash-named internal chunk (the `TS2742` family).
  *
- * Lives in `target-postgres` because codec types describe the target's value
- * space - both the control adapter (introspection / schema verification) and
- * the runtime adapter (encode/decode) share the same definitions, and the
- * target package is the natural home that both adapters depend on.
- *
- * Runtime codec implementations are provided by the runtime adapter's
- * codec registry, which is built from `core/codecs.ts`.
+ * Lives in `target-postgres` because codec types describe the target's value space — both the control adapter (introspection / schema verification) and the runtime adapter (encode/decode) share the same definitions, and the target package is the natural home that both adapters depend on.
  */
 
 import type { JsonValue } from '@prisma-next/contract/types';
-import type { CodecTypes as CoreCodecTypes } from '../core/codecs';
+import type { ExtractedCodecTypes, Resolve } from '../core/codec-type-map';
 
-export type CodecTypes = CoreCodecTypes;
+export type CodecTypes = Resolve<ExtractedCodecTypes>;
 
 export type { JsonValue };
-export { dataTypes } from '../core/codecs';
 
 type Branded<T, Shape extends Record<string, unknown>> = T & {
   readonly [K in keyof Shape]: Shape[K];