@prisma-next/sql-runtime 0.5.0-dev.3 → 0.5.0-dev.31

package/src/sql-context.ts

@@ -1,4 +1,6 @@
 import type { Contract, ExecutionMutationDefaultValue } from '@prisma-next/contract/types';
+import type { CodecDescriptor } from '@prisma-next/framework-components/codec';
+import { synthesizeNonParameterizedDescriptor } from '@prisma-next/framework-components/codec';
 import type { ComponentDescriptor } from '@prisma-next/framework-components/components';
 import { checkContractComponentRequirements } from '@prisma-next/framework-components/components';
 import {
@@ -14,7 +16,7 @@ import {
   type RuntimeTargetInstance,
 } from '@prisma-next/framework-components/execution';
 import { runtimeError } from '@prisma-next/framework-components/runtime';
-import type { SqlStorage, StorageTypeInstance } from '@prisma-next/sql-contract/types';
+import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import {
   createSqlOperationRegistry,
   type SqlOperationDescriptor,
@@ -22,39 +24,41 @@ import {
 import type {
   Adapter,
   AnyQueryAst,
-  CodecParamsDescriptor,
+  Codec,
   CodecRegistry,
+  ContractCodecRegistry,
   LoweredStatement,
+  SqlCodecInstanceContext,
   SqlDriver,
 } from '@prisma-next/sql-relational-core/ast';
 import { createCodecRegistry } from '@prisma-next/sql-relational-core/ast';
 import type {
   AppliedMutationDefault,
+  CodecDescriptorRegistry,
   ExecutionContext,
   JsonSchemaValidateFn,
   JsonSchemaValidatorRegistry,
   MutationDefaultsOptions,
   TypeHelperRegistry,
 } from '@prisma-next/sql-relational-core/query-lane-context';
-import { type as arktype } from 'arktype';
 
 /**
  * Runtime parameterized codec descriptor.
- * Provides validation schema and optional init hook for codecs that support type parameters.
- * Used at runtime to validate typeParams and create type helpers.
  *
- * This is a type alias for `CodecParamsDescriptor` from the AST layer,
- * which is the shared definition used by both adapter and runtime.
+ * The unified `CodecDescriptor<P>` shape applied to parameterized codecs
+ * — `paramsSchema: StandardSchemaV1<P>` for JSON-boundary validation,
+ * `factory: (P) => (CodecInstanceContext) => Codec` for the curried higher-order codec.
+ * The factory is called once per `storage.types` instance (or once per
+ * inline-`typeParams` column); per-instance state lives in the closure.
+ *
+ * Codec-registry-unification spec § Decision.
  */
-export type RuntimeParameterizedCodecDescriptor<
-  TParams = Record<string, unknown>,
-  THelper = unknown,
-> = CodecParamsDescriptor<TParams, THelper>;
+export type RuntimeParameterizedCodecDescriptor<P = Record<string, unknown>> = CodecDescriptor<P>;
 
 export interface SqlStaticContributions {
   readonly codecs: () => CodecRegistry;
   // biome-ignore lint/suspicious/noExplicitAny: needed for covariance with concrete descriptor types
-  readonly parameterizedCodecs: () => ReadonlyArray<RuntimeParameterizedCodecDescriptor<any, any>>;
+  readonly parameterizedCodecs: () => ReadonlyArray<RuntimeParameterizedCodecDescriptor<any>>;
   readonly queryOperations?: () => ReadonlyArray<SqlOperationDescriptor>;
   readonly mutationDefaultGenerators?: () => ReadonlyArray<RuntimeMutationDefaultGenerator>;
 }
@@ -206,9 +210,16 @@ function validateTypeParams(
   codecDescriptor: RuntimeParameterizedCodecDescriptor,
   context: { typeName?: string; tableName?: string; columnName?: string },
 ): Record<string, unknown> {
-  const result = codecDescriptor.paramsSchema(typeParams);
-  if (result instanceof arktype.errors) {
-    const messages = result.map((p: { message: string }) => p.message).join('; ');
+  const result = codecDescriptor.paramsSchema['~standard'].validate(typeParams);
+  if (result instanceof Promise) {
+    throw runtimeError(
+      'RUNTIME.TYPE_PARAMS_INVALID',
+      `paramsSchema for codec '${codecDescriptor.codecId}' returned a Promise; runtime validation requires a synchronous Standard Schema validator.`,
+      { ...context, codecId: codecDescriptor.codecId, typeParams },
+    );
+  }
+  if (result.issues) {
+    const messages = result.issues.map((issue) => issue.message).join('; ');
     const locationInfo = context.typeName
       ? `type '${context.typeName}'`
       : `column '${context.tableName}.${context.columnName}'`;
@@ -218,7 +229,7 @@ function validateTypeParams(
       { ...context, codecId: codecDescriptor.codecId, typeParams },
     );
   }
-  return result as Record<string, unknown>;
+  return result.value as Record<string, unknown>;
 }
 
 function collectParameterizedCodecDescriptors(
@@ -242,32 +253,116 @@ function collectParameterizedCodecDescriptors(
   return descriptors;
 }
 
+/**
+ * Build the unified descriptor map. Combines parameterized descriptors
+ * (which already ship as `CodecDescriptor`s) with synthesized descriptors
+ * for non-parameterized codecs registered through the legacy `codecs:`
+ * slot. Codec ids that ship a parameterized descriptor take precedence —
+ * even when the legacy registry registers a representative codec under
+ * the same id, the parameterized descriptor is the authoritative source.
+ *
+ * Codec-registry-unification spec § Decision: every codec resolves
+ * through one descriptor map; reads are non-branching.
+ */
+function buildCodecDescriptorRegistry(
+  codecRegistry: CodecRegistry,
+  parameterizedDescriptors: Map<string, RuntimeParameterizedCodecDescriptor>,
+): CodecDescriptorRegistry {
+  type AnyDescriptor = CodecDescriptor<unknown>;
+  const byId = new Map<string, AnyDescriptor>();
+  const byTargetType = new Map<string, Array<AnyDescriptor>>();
+
+  function registerInIndices(descriptor: AnyDescriptor): void {
+    byId.set(descriptor.codecId, descriptor);
+    for (const targetType of descriptor.targetTypes) {
+      const list = byTargetType.get(targetType);
+      if (list) {
+        list.push(descriptor);
+      } else {
+        byTargetType.set(targetType, [descriptor]);
+      }
+    }
+  }
+
+  // The descriptor map is heterogeneous in `P` — each codec id has its own
+  // params shape. The public `CodecDescriptorRegistry` interface widens to
+  // `CodecDescriptor<unknown>` and consumers narrow per codec id at the
+  // call site (the descriptor's `paramsSchema` validates JSON-sourced
+  // params before the factory ever sees them, so the runtime narrow is
+  // safe). The cast at registration goes through `unknown` because
+  // `CodecDescriptor<P>` is invariant in `P` (the `factory` and
+  // `renderOutputType` slots use `P` contravariantly).
+  for (const descriptor of parameterizedDescriptors.values()) {
+    registerInIndices(descriptor as unknown as AnyDescriptor);
+  }
+
+  for (const codec of codecRegistry.values()) {
+    if (byId.has(codec.id)) continue;
+    registerInIndices(synthesizeNonParameterizedDescriptor(codec) as unknown as AnyDescriptor);
+  }
+
+  return {
+    descriptorFor(codecId: string): AnyDescriptor | undefined {
+      return byId.get(codecId);
+    },
+    *values(): IterableIterator<AnyDescriptor> {
+      yield* byId.values();
+    },
+    byTargetType(targetType: string): readonly AnyDescriptor[] {
+      return byTargetType.get(targetType) ?? Object.freeze([]);
+    },
+  };
+}
+
+function collectTypeRefSites(
+  storage: SqlStorage,
+): Map<string, Array<{ readonly table: string; readonly column: string }>> {
+  const sites = new Map<string, Array<{ readonly table: string; readonly column: string }>>();
+  for (const [tableName, table] of Object.entries(storage.tables)) {
+    for (const [columnName, column] of Object.entries(table.columns)) {
+      if (typeof column.typeRef !== 'string') continue;
+      const list = sites.get(column.typeRef);
+      const entry = { table: tableName, column: columnName };
+      if (list) {
+        list.push(entry);
+      } else {
+        sites.set(column.typeRef, [entry]);
+      }
+    }
+  }
+  return sites;
+}
+
 function initializeTypeHelpers(
-  storageTypes: Record<string, StorageTypeInstance> | undefined,
+  storage: SqlStorage,
   codecDescriptors: Map<string, RuntimeParameterizedCodecDescriptor>,
 ): TypeHelperRegistry {
   const helpers: TypeHelperRegistry = {};
+  const storageTypes = storage.types;
 
   if (!storageTypes) {
     return helpers;
   }
 
+  const typeRefSites = collectTypeRefSites(storage);
+
   for (const [typeName, typeInstance] of Object.entries(storageTypes)) {
     const descriptor = codecDescriptors.get(typeInstance.codecId);
 
-    if (descriptor) {
-      const validatedParams = validateTypeParams(typeInstance.typeParams, descriptor, {
-        typeName,
-      });
-
-      if (descriptor.init) {
-        helpers[typeName] = descriptor.init(validatedParams);
-      } else {
-        helpers[typeName] = typeInstance;
-      }
-    } else {
+    if (!descriptor) {
+      // No parameterized descriptor for this codec id — store the raw
+      // type instance for callers that need typeParams metadata.
       helpers[typeName] = typeInstance;
+      continue;
     }
+
+    const validatedParams = validateTypeParams(typeInstance.typeParams, descriptor, {
+      typeName,
+    });
+
+    const usedAt = typeRefSites.get(typeName) ?? [];
+    const ctx: SqlCodecInstanceContext = { name: typeName, usedAt };
+    helpers[typeName] = descriptor.factory(validatedParams)(ctx);
   }
 
   return helpers;
@@ -290,67 +385,217 @@ function validateColumnTypeParams(
 }
 
 /**
- * Builds a registry of compiled JSON Schema validators by scanning the contract
- * for columns whose codec descriptor provides an `init` hook returning `{ validate }`.
+ * View of a codec that exposes a per-instance JSON-schema `validate`
+ * function. Codecs declare this contract by including the
+ * `'json-validator'` `CodecTrait` in their `traits` array; the trait is
+ * the gate that lets `extractValidator` resolve from structurally-typed
+ * `unknown` to this typed view.
+ */
+type JsonValidatorCodec = {
+  readonly traits?: ReadonlyArray<unknown>;
+  readonly validate: JsonSchemaValidateFn;
+};
+
+function hasJsonValidatorTrait(candidate: unknown): candidate is JsonValidatorCodec {
+  if (candidate === null || typeof candidate !== 'object') return false;
+  const traits = (candidate as { readonly traits?: unknown }).traits;
+  if (!Array.isArray(traits)) return false;
+  if (!traits.includes('json-validator')) return false;
+  const validate = (candidate as { readonly validate?: unknown }).validate;
+  return typeof validate === 'function';
+}
+
+function extractValidator(candidate: unknown): JsonSchemaValidateFn | undefined {
+  return hasJsonValidatorTrait(candidate) ? candidate.validate : undefined;
+}
+
+function isResolvedCodec(candidate: unknown): candidate is Codec {
+  return (
+    candidate !== null &&
+    typeof candidate === 'object' &&
+    'id' in candidate &&
+    'decode' in candidate
+  );
+}
+
+/**
+ * Walk the contract's `storage.tables[].columns[]` and resolve each
+ * column to a `Codec` through the unified descriptor map. Per-instance
+ * behavior:
+ *
+ * - **typeRef columns**: reuse the resolved codec materialized once by
+ *   `initializeTypeHelpers` for the `storage.types` entry. Multiple
+ *   columns sharing one typeRef share one codec instance.
+ * - **inline-typeParams columns**: call `descriptor.factory(typeParams)
+ *   (ctx)` once per column (per-column anonymous instance).
+ * - **non-parameterized columns**: call `descriptor.factory()(ctx)`
+ *   once. The synthesized descriptor's factory is constant — every call
+ *   returns the same shared codec instance — so columns sharing a non-
+ *   parameterized codec id share one resolved codec without explicit
+ *   caching.
  *
- * Handles both:
- * - Inline `typeParams.schema` on columns
- * - `typeRef` → `storage.types[ref]` with init hook results already in `types` registry
+ * Combines what `initializeTypeHelpers` (named-instance walk) and the
+ * old `buildJsonSchemaValidatorRegistry` (per-column walk) used to do
+ * separately: one walk over all columns, one resolved codec per column,
+ * one trait-gated validator extraction per column. The result drives
+ * both the dispatch registry (`ContractCodecRegistry.forColumn`) and the
+ * validator registry.
+ *
+ * Codec-registry-unification spec § AC-4: every column resolves through
+ * one descriptor map without branching on parameterization.
  */
-function buildJsonSchemaValidatorRegistry(
+function buildContractCodecRegistry(
   contract: Contract<SqlStorage>,
+  codecDescriptors: CodecDescriptorRegistry,
+  legacyCodecRegistry: CodecRegistry,
   types: TypeHelperRegistry,
-  codecDescriptors: Map<string, RuntimeParameterizedCodecDescriptor>,
-): JsonSchemaValidatorRegistry | undefined {
+  parameterizedDescriptors: Map<string, RuntimeParameterizedCodecDescriptor>,
+): {
+  readonly registry: ContractCodecRegistry;
+  readonly jsonValidators: JsonSchemaValidatorRegistry | undefined;
+} {
+  const byColumn = new Map<string, Codec>();
+  const byCodecId = new Map<string, Codec>();
+  // Codec ids whose `byCodecId` entry is ambiguous — multiple distinct
+  // resolved instances landed under the same parameterized codec id (e.g.
+  // `Vector<1024>` and `Vector<1536>` both registering under
+  // `pg/vector@1`). The encode-side `forCodecId` fallback rejects these
+  // ids so a DSL-param without a column ref cannot silently bind to the
+  // wrong instance. Retires when AC-5's `ParamRef.refs` plumbing lands
+  // (TML-2357).
+  const ambiguousCodecIds = new Set<string>();
   const validators = new Map<string, JsonSchemaValidateFn>();
 
-  // Collect codec IDs that have init hooks (these produce { validate } helpers)
-  const codecIdsWithInit = new Set<string>();
-  for (const [codecId, descriptor] of codecDescriptors) {
-    if (descriptor.init) {
-      codecIdsWithInit.add(codecId);
-    }
-  }
-
-  if (codecIdsWithInit.size === 0) {
-    return undefined;
-  }
-
   for (const [tableName, table] of Object.entries(contract.storage.tables)) {
     for (const [columnName, column] of Object.entries(table.columns)) {
-      if (!codecIdsWithInit.has(column.codecId)) continue;
-
-      const key = `${tableName}.${columnName}`;
-
-      // Case 1: column references a named type → validator already compiled via init hook
-      if (column.typeRef) {
-        const helper = types[column.typeRef] as { validate?: JsonSchemaValidateFn } | undefined;
-        if (helper?.validate) {
-          validators.set(key, helper.validate);
+      const columnKey = `${tableName}.${columnName}`;
+      const descriptor = codecDescriptors.descriptorFor(column.codecId);
+
+      let resolvedCodec: Codec | undefined;
+
+      if (descriptor) {
+        const isParameterized = parameterizedDescriptors.has(column.codecId);
+
+        if (column.typeRef) {
+          // The named instance was already materialized once by
+          // `initializeTypeHelpers`; reuse it so multiple columns sharing
+          // the same typeRef share one codec instance (and any per-
+          // instance helper state on it).
+          const helper = types[column.typeRef];
+          if (isResolvedCodec(helper)) {
+            resolvedCodec = helper;
+          }
+        } else if (column.typeParams && isParameterized) {
+          const parameterizedDescriptor = parameterizedDescriptors.get(column.codecId);
+          if (parameterizedDescriptor) {
+            const validatedParams = validateTypeParams(column.typeParams, parameterizedDescriptor, {
+              tableName,
+              columnName,
+            });
+            const ctx: SqlCodecInstanceContext = {
+              name: `<anon:${tableName}.${columnName}>`,
+              usedAt: [{ table: tableName, column: columnName }],
+            };
+            resolvedCodec = parameterizedDescriptor.factory(validatedParams)(ctx);
+          }
+        } else if (!isParameterized) {
+          // Non-parameterized column. Cache the resolved codec by codec
+          // id — the synthesized descriptor's factory is constant for
+          // non-parameterized codecs, so columns sharing this codec id
+          // share one resolved instance.
+          let cached = byCodecId.get(column.codecId);
+          if (!cached) {
+            const ctx: SqlCodecInstanceContext = {
+              name: `<shared:${column.codecId}>`,
+              usedAt: [{ table: tableName, column: columnName }],
+            };
+            // `synthesizeNonParameterizedDescriptor` produces a
+            // `CodecDescriptor<void>` whose factory ignores its params
+            // and ctx; the runtime's `void` value is `undefined`. The
+            // structural cast goes through `unknown` to satisfy the
+            // heterogeneous-`P` registry boundary (the factory's
+            // declared `P` is `any` here; the consumer narrows per
+            // codec id). The cast narrows the descriptor's
+            // family-agnostic `CodecInstanceContext` slot to the SQL
+            // `SqlCodecInstanceContext` we pass at this call site —
+            // function-argument contravariance makes the narrow safe
+            // (a callee that accepts the base will also accept the
+            // SQL extension). Per spec § Non-functional constraints.
+            const voidFactory = descriptor.factory as unknown as (
+              params: undefined,
+            ) => (ctx: SqlCodecInstanceContext) => Codec;
+            cached = voidFactory(undefined)(ctx);
+            byCodecId.set(column.codecId, cached);
+          }
+          resolvedCodec = cached;
         }
-        continue;
+        // else: parameterized codec id with no typeRef and no typeParams
+        // — this is the legitimate "undimensioned" form for codecs that
+        // ship a no-params column variant alongside a parameterized one
+        // (e.g. pgvector's `vectorColumn` vs. `vector(N)`). Leave
+        // `resolvedCodec` undefined; encode/decode for this column flows
+        // through `forCodecId` (the AC-5-deferred carve-out documented
+        // in `relational-core/src/ast/codec-types.ts`). The fallback
+        // works for these cases because their wire format is
+        // params-independent (vector formats `[v1,v2,...]` regardless
+        // of declared length).
       }
 
-      // Case 2: inline typeParams with schema → compile via init hook
-      if (column.typeParams) {
-        const descriptor = codecDescriptors.get(column.codecId);
-        if (descriptor?.init) {
-          const helper = descriptor.init(column.typeParams) as
-            | { validate?: JsonSchemaValidateFn }
-            | undefined;
-          if (helper?.validate) {
-            validators.set(key, helper.validate);
-          }
+      if (resolvedCodec) {
+        byColumn.set(columnKey, resolvedCodec);
+        const validate = extractValidator(resolvedCodec);
+        if (validate) {
+          validators.set(columnKey, validate);
+        }
+        const existing = byCodecId.get(column.codecId);
+        if (existing === undefined) {
+          byCodecId.set(column.codecId, resolvedCodec);
+        } else if (existing !== resolvedCodec && parameterizedDescriptors.has(column.codecId)) {
+          ambiguousCodecIds.add(column.codecId);
         }
       }
     }
   }
 
-  if (validators.size === 0) return undefined;
-  return {
-    get: (key: string) => validators.get(key),
-    size: validators.size,
+  const registry: ContractCodecRegistry = {
+    forColumn(table, column) {
+      return byColumn.get(`${table}.${column}`);
+    },
+    forCodecId(codecId) {
+      // Codec-id-only fallback for sites without a column ref (encode-
+      // side DSL params whose `ParamRef.refs` isn't populated). Prefer
+      // the contract-walk-derived shared codec; fall back to the legacy
+      // `codecRegistry.get` for parameterized codec ids whose contracts
+      // don't have a typeRef/typeParams column the walk could resolve
+      // through. The legacy fallback retires once `ParamRef.refs` is
+      // threaded everywhere (TML-2357).
+      //
+      // Reject ambiguous parameterized fallbacks: if the contract walk
+      // resolved more than one distinct codec instance under this id
+      // (e.g. multiple vector dimensions, multiple arktype-json
+      // schemas), the codec-id-keyed lookup cannot honor the call site
+      // — fail fast rather than bind to whichever instance happened to
+      // land first.
+      if (ambiguousCodecIds.has(codecId)) {
+        throw runtimeError(
+          'RUNTIME.TYPE_PARAMS_INVALID',
+          `Codec '${codecId}' resolves to multiple parameterized instances; column-aware dispatch is required.`,
+          { codecId },
+        );
+      }
+      return byCodecId.get(codecId) ?? legacyCodecRegistry.get(codecId);
+    },
   };
+
+  const jsonValidators: JsonSchemaValidatorRegistry | undefined =
+    validators.size > 0
+      ? {
+          get: (key: string) => validators.get(key),
+          size: validators.size,
+        }
+      : undefined;
+
+  return { registry, jsonValidators };
 }
 
 function collectMutationDefaultGenerators(
@@ -476,23 +721,32 @@ export function createExecutionContext<
   }
 
   const parameterizedCodecDescriptors = collectParameterizedCodecDescriptors(contributors);
+  const codecDescriptors = buildCodecDescriptorRegistry(
+    codecRegistry,
+    parameterizedCodecDescriptors,
+  );
   const mutationDefaultGeneratorRegistry = collectMutationDefaultGenerators(contributors);
 
   if (parameterizedCodecDescriptors.size > 0) {
     validateColumnTypeParams(contract.storage, parameterizedCodecDescriptors);
   }
 
-  const types = initializeTypeHelpers(contract.storage.types, parameterizedCodecDescriptors);
+  const types = initializeTypeHelpers(contract.storage, parameterizedCodecDescriptors);
 
-  const jsonSchemaValidators = buildJsonSchemaValidatorRegistry(
-    contract,
-    types,
-    parameterizedCodecDescriptors,
-  );
+  const { registry: contractCodecs, jsonValidators: jsonSchemaValidators } =
+    buildContractCodecRegistry(
+      contract,
+      codecDescriptors,
+      codecRegistry,
+      types,
+      parameterizedCodecDescriptors,
+    );
 
   return {
     contract,
     codecs: codecRegistry,
+    contractCodecs,
+    codecDescriptors,
     queryOperations: queryOperationRegistry,
     types,
     ...(jsonSchemaValidators ? { jsonSchemaValidators } : {}),

package/src/sql-family-adapter.ts

@@ -1,8 +1,9 @@
-import type { Contract, ExecutionPlan } from '@prisma-next/contract/types';
+import type { Contract } from '@prisma-next/contract/types';
+import type { ExecutionPlan } from '@prisma-next/framework-components/runtime';
 import { runtimeError } from '@prisma-next/framework-components/runtime';
-import type { MarkerReader, RuntimeFamilyAdapter } from '@prisma-next/runtime-executor';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import type { AdapterProfile } from '@prisma-next/sql-relational-core/ast';
+import type { MarkerReader, RuntimeFamilyAdapter } from './runtime-spi';
 
 export class SqlFamilyAdapter<TContract extends Contract<SqlStorage>>
   implements RuntimeFamilyAdapter<TContract>

package/src/sql-marker.ts

@@ -1,4 +1,4 @@
-import type { MarkerStatement } from '@prisma-next/runtime-executor';
+import type { MarkerStatement } from '@prisma-next/sql-relational-core/ast';
 
 export interface SqlStatement {
   readonly sql: string;
@@ -12,6 +12,15 @@ export interface WriteMarkerInput {
   readonly canonicalVersion?: number;
   readonly appTag?: string;
   readonly meta?: Record<string, unknown>;
+  /**
+   * Applied-invariants set on the marker.
+   *
+   * - `undefined` → existing column left untouched. Sign and
+   *   verify-database paths use this; they don't accumulate invariants.
+   * - explicit value (including `[]`) → column overwritten with
+   *   exactly that value.
+   */
+  readonly invariants?: readonly string[];
 }
 
 export const ensureSchemaStatement: SqlStatement = {
@@ -28,7 +37,8 @@ export const ensureTableStatement: 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: [],
 };
@@ -42,7 +52,8 @@ export function readContractMarker(): MarkerStatement {
       canonical_version,
       updated_at,
       app_tag,
-      meta
+      meta,
+      invariants
     from prisma_contract.marker
     where id = $1`,
     params: [1],
@@ -54,52 +65,56 @@ export interface WriteContractMarkerStatements {
   readonly update: SqlStatement;
 }
 
-export function writeContractMarker(input: WriteMarkerInput): WriteContractMarkerStatements {
-  const baseParams: readonly unknown[] = [
-    1,
-    input.storageHash,
-    input.profileHash,
-    input.contractJson ?? null,
-    input.canonicalVersion ?? null,
-    input.appTag ?? null,
-    JSON.stringify(input.meta ?? {}),
+/**
+ * Variable columns that participate in INSERT/UPDATE alongside the
+ * always-on `id = $1` and `updated_at = now()`. Each column declares
+ * its name, optional cast type, and parameter value; the placeholder
+ * (`$N`) is computed positionally below — adding or reordering a
+ * column doesn't desync indices. `invariants` only appears when the
+ * caller supplies it — see `WriteMarkerInput.invariants`.
+ */
+function markerColumns(
+  input: WriteMarkerInput,
+): ReadonlyArray<{ readonly name: string; readonly type?: string; readonly param: unknown }> {
+  return [
+    { name: 'core_hash', param: input.storageHash },
+    { name: 'profile_hash', param: input.profileHash },
+    { name: 'contract_json', type: 'jsonb', param: input.contractJson ?? null },
+    { name: 'canonical_version', param: input.canonicalVersion ?? null },
+    { name: 'app_tag', param: input.appTag ?? null },
+    { name: 'meta', type: 'jsonb', param: JSON.stringify(input.meta ?? {}) },
+    ...(input.invariants !== undefined
+      ? [{ name: 'invariants' as const, type: 'text[]' as const, param: input.invariants }]
+      : []),
   ];
+}
 
-  const insert: SqlStatement = {
-    sql: `insert into prisma_contract.marker (
-        id,
-        core_hash,
-        profile_hash,
-        contract_json,
-        canonical_version,
-        updated_at,
-        app_tag,
-        meta
-      ) values (
-        $1,
-        $2,
-        $3,
-        $4::jsonb,
-        $5,
-        now(),
-        $6,
-        $7::jsonb
-      )`,
-    params: baseParams,
-  };
+export function writeContractMarker(input: WriteMarkerInput): WriteContractMarkerStatements {
+  const cols = markerColumns(input);
+  // $1 is reserved for `id`; subsequent positions follow the order of cols.
+  const placed = cols.map((c, i) => ({
+    name: c.name,
+    expr: c.type ? `$${i + 2}::${c.type}` : `$${i + 2}`,
+    param: c.param,
+  }));
+  const params: readonly unknown[] = [1, ...placed.map((c) => c.param)];
 
-  const update: SqlStatement = {
-    sql: `update prisma_contract.marker set
-        core_hash = $2,
-        profile_hash = $3,
-        contract_json = $4::jsonb,
-        canonical_version = $5,
-        updated_at = now(),
-        app_tag = $6,
-        meta = $7::jsonb
-      where id = $1`,
-    params: baseParams,
-  };
+  // `updated_at = now()` is a SQL literal with no parameter slot, so it
+  // sits outside `placed` and is appended directly to each statement.
+  const insertColumns = ['id', ...placed.map((c) => c.name), 'updated_at'].join(', ');
+  const insertValues = ['$1', ...placed.map((c) => c.expr), 'now()'].join(', ');
+  const setClauses = [...placed.map((c) => `${c.name} = ${c.expr}`), 'updated_at = now()'].join(
+    ', ',
+  );
 
-  return { insert, update };
+  return {
+    insert: {
+      sql: `insert into prisma_contract.marker (${insertColumns}) values (${insertValues})`,
+      params,
+    },
+    update: {
+      sql: `update prisma_contract.marker set ${setClauses} where id = $1`,
+      params,
+    },
+  };
 }