@prisma-next/family-sql 0.14.0 → 0.15.0-dev.1

package/src/core/diff/schema-verify.ts

@@ -0,0 +1,324 @@
+/**
+ * The differ-based SQL schema verify: post-diff filters and verdict.
+ *
+ * The generic node differ (`diffSchemas`) reports every node-level
+ * difference between the derived expected tree and the introspected actual
+ * tree. This module is the consumer side the spec assigns to the SQL
+ * family: strict-mode extras gating and control-policy disposition are
+ * reason/kind-keyed filters applied AFTER the diff — never inside it — and
+ * the verify verdict derives from the filtered issue list.
+ *
+ * `verifySqlSchemaByDiff` wraps the verdict in the issue-based result
+ * envelope — this is THE SQL schema verify (the legacy relational walk and
+ * its verification tree are retired).
+ */
+
+import type { Contract, ControlPolicy } from '@prisma-next/contract/types';
+import { effectiveControlPolicy } from '@prisma-next/contract/types';
+import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
+import type {
+  DiffSubjectGranularity,
+  SchemaDiffIssue,
+  VerifierIssueCategory,
+  VerifierOutcome,
+  VerifyDatabaseSchemaResult,
+} from '@prisma-next/framework-components/control';
+import { dispositionForCategory } from '@prisma-next/framework-components/control';
+import { isStorageTypeInstance, type SqlStorage } from '@prisma-next/sql-contract/types';
+import { RelationalSchemaNodeKind, type SqlSchemaIRNode } from '@prisma-next/sql-schema-ir/types';
+import { blindCast } from '@prisma-next/utils/casts';
+import { ifDefined } from '@prisma-next/utils/defined';
+import { extractCodecControlHooks } from '../assembly';
+import type { SqlSchemaDiffFn } from '../migrations/schema-differ';
+import type { CodecControlHooks } from '../migrations/types';
+import { verifierDisposition } from './verifier-disposition';
+
+// ============================================================================
+// Subject-granularity classification — nodeKind → framework-neutral granularity
+// ============================================================================
+
+function issueNode(issue: SchemaDiffIssue): SqlSchemaIRNode | undefined {
+  const node = issue.expected ?? issue.actual;
+  if (node === undefined) return undefined;
+  return blindCast<
+    SqlSchemaIRNode,
+    'every node in a SQL schema diff tree is a SqlSchemaIRNode; nodeKind is its identity'
+  >(node);
+}
+
+/**
+ * Resolves an issue's framework-neutral {@link DiffSubjectGranularity} on
+ * demand, from the issue's node's `nodeKind` via the target-provided
+ * `granularityOf` map. The node carries only its `nodeKind` identity, never a
+ * classification, and nothing is stamped onto the issue — every consumer
+ * (the family verdict below, the framework aggregate's unclaimed-elements
+ * sweep via {@link import('@prisma-next/framework-components/control').SchemaSubjectClassifierCapable})
+ * calls this the same way, resolved by the family/target that owns the node
+ * vocabulary. `undefined` for an issue with no node.
+ */
+export function classifyDiffSubjectGranularity(
+  issue: SchemaDiffIssue,
+  granularityOf: (nodeKind: string) => DiffSubjectGranularity,
+): DiffSubjectGranularity | undefined {
+  const node = issueNode(issue);
+  return node === undefined ? undefined : granularityOf(node.nodeKind);
+}
+
+/**
+ * Resolves an issue's storage `entityKind` on demand, from the issue's
+ * node's `nodeKind` via the target-provided `entityKindOf` map — the sibling
+ * of {@link classifyDiffSubjectGranularity}, called the same way by the same
+ * consumers (via
+ * {@link import('@prisma-next/framework-components/control').SchemaSubjectClassifierCapable}).
+ * `undefined` for an issue with no node, or for a node kind with no storage
+ * entity of its own.
+ */
+export function classifyDiffEntityKind(
+  issue: SchemaDiffIssue,
+  entityKindOf: (nodeKind: string) => string | undefined,
+): string | undefined {
+  const node = issueNode(issue);
+  return node === undefined ? undefined : entityKindOf(node.nodeKind);
+}
+
+// ============================================================================
+// Issue classification — subject granularity + reason → target-neutral category
+// ============================================================================
+
+/**
+ * Re-keys the legacy `classifySqlVerifierIssueKind` category mapping on the
+ * issue's {@link DiffSubjectGranularity} (resolved via `granularityOf`) + the
+ * issue reason. The vocabulary maps one-to-one: an undeclared live entity or
+ * namespace is `extraTopLevelObject`, an undeclared live field
+ * `extraNestedElement`, undeclared auxiliaries (constraints, indexes,
+ * defaults) and structural leaves (policies) `extraAuxiliary`; a value-set
+ * drift on a check node is `valueDrift`; every other paired divergence is
+ * `declaredIncompatible`; anything the database lacks is `declaredMissing`.
+ * `granularityOf` is the target's classifier, so target and extension node
+ * kinds classify without the family importing them.
+ */
+export function classifySqlDiffIssue(
+  issue: SchemaDiffIssue,
+  granularityOf: (nodeKind: string) => DiffSubjectGranularity,
+): VerifierIssueCategory {
+  if (issue.reason === 'not-found') {
+    return 'declaredMissing';
+  }
+  if (issue.reason === 'not-expected') {
+    const granularity = classifyDiffSubjectGranularity(issue, granularityOf);
+    if (granularity === 'entity' || granularity === 'namespace') {
+      return 'extraTopLevelObject';
+    }
+    if (granularity === 'field') {
+      return 'extraNestedElement';
+    }
+    return 'extraAuxiliary';
+  }
+  if (issueNode(issue)?.nodeKind === RelationalSchemaNodeKind.check) {
+    return 'valueDrift';
+  }
+  return 'declaredIncompatible';
+}
+
+/**
+ * Whether a `not-expected` issue is a strict-mode-only finding. The legacy
+ * walk detected every relational extra (namespaces, entities, fields, and
+ * their auxiliaries) only under `--strict`; the structural diff (roots, RLS
+ * policies, roles) was never strict-gated — its extras fail in both modes.
+ * Keyed on the issue's granularity, resolved via `granularityOf`.
+ */
+function isStrictOnlyExtra(
+  issue: SchemaDiffIssue,
+  granularityOf: (nodeKind: string) => DiffSubjectGranularity,
+): boolean {
+  const granularity = classifyDiffSubjectGranularity(issue, granularityOf);
+  return (
+    granularity === 'namespace' ||
+    granularity === 'entity' ||
+    granularity === 'field' ||
+    granularity === 'auxiliary'
+  );
+}
+
+// ============================================================================
+// The post-diff filter + verdict
+// ============================================================================
+
+export interface SqlDiffVerdictInput {
+  /** The full, ownership-scoped diff issue list from the target's differ. */
+  readonly issues: readonly SchemaDiffIssue[];
+  /** Resolves a diff issue's subject table's declared control policy directly from the contract. */
+  readonly resolveControlPolicy: (issue: SchemaDiffIssue) => ControlPolicy | undefined;
+  readonly strict: boolean;
+  readonly defaultControlPolicy: ControlPolicy | undefined;
+  /** The target's classifier: a diff issue node's `nodeKind` → its subject granularity. */
+  readonly granularityOf: (nodeKind: string) => DiffSubjectGranularity;
+}
+
+export interface SqlDiffVerdict {
+  readonly failures: readonly SchemaDiffIssue[];
+  readonly warnings: readonly SchemaDiffIssue[];
+}
+
+/**
+ * Applies the two consumer filters to a diff issue list: strict gating
+ * (relational `not-expected` findings drop in lenient mode) and
+ * control-policy disposition (each surviving issue grades against its
+ * subject table's effective policy; suppressed issues drop, `observed`
+ * subjects warn). The verify verdict is `failures.length === 0`.
+ */
+export function computeSqlDiffVerdict(input: SqlDiffVerdictInput): SqlDiffVerdict {
+  const failures: SchemaDiffIssue[] = [];
+  const warnings: SchemaDiffIssue[] = [];
+  for (const issue of input.issues) {
+    if (
+      !input.strict &&
+      issue.reason === 'not-expected' &&
+      isStrictOnlyExtra(issue, input.granularityOf)
+    ) {
+      continue;
+    }
+    const tablePolicy = input.resolveControlPolicy(issue);
+    const policy = effectiveControlPolicy(tablePolicy, input.defaultControlPolicy);
+    const disposition: VerifierOutcome = dispositionForCategory(
+      policy,
+      classifySqlDiffIssue(issue, input.granularityOf),
+    );
+    if (disposition === 'suppress') continue;
+    if (disposition === 'warn') {
+      warnings.push(issue);
+      continue;
+    }
+    failures.push(issue);
+  }
+  return { failures, warnings };
+}
+
+// ============================================================================
+// Storage-types check — the codec verifyType hook path
+// ============================================================================
+
+export interface StorageTypeVerdictInput {
+  readonly contract: Contract<SqlStorage>;
+  /**
+   * Expected/actual namespace-node pairs the target's differ input produced:
+   * for a namespaced tree, one entry per expected namespace with a
+   * non-empty table set, paired by DDL schema name (absent actual side for
+   * a schema the database lacks); a flat tree is the sole pair.
+   */
+  readonly namespacePairs: ReadonlyArray<{
+    readonly actual: SqlSchemaIRNode | undefined;
+  }>;
+  readonly codecHooks: ReadonlyMap<string, CodecControlHooks>;
+}
+
+/**
+ * Runs the codec `verifyType` hooks the way the legacy walk did: once per
+ * contract namespace with tables, against that namespace's paired actual
+ * node (the hook reads namespace-scoped state such as `enums` off it).
+ * Issue dispositions grade against the contract default policy, matching
+ * the legacy `pushTypeNode` semantics.
+ */
+export interface StorageTypeVerdict {
+  readonly failures: readonly SchemaDiffIssue[];
+  readonly warnings: readonly SchemaDiffIssue[];
+}
+
+export function computeStorageTypeVerdict(input: StorageTypeVerdictInput): StorageTypeVerdict {
+  const failures: SchemaDiffIssue[] = [];
+  const warnings: SchemaDiffIssue[] = [];
+  const policy = effectiveControlPolicy(undefined, input.contract.defaultControlPolicy);
+  for (const pair of input.namespacePairs) {
+    if (pair.actual === undefined) continue;
+    for (const [typeName, typeInstance] of Object.entries(input.contract.storage.types ?? {})) {
+      if (!isStorageTypeInstance(typeInstance)) continue;
+      const hook = input.codecHooks.get(typeInstance.codecId);
+      if (!hook?.verifyType) continue;
+      const typeIssues = hook.verifyType({ typeName, typeInstance, schema: pair.actual });
+      for (const issue of typeIssues) {
+        const disposition = verifierDisposition(policy, issue);
+        if (disposition === 'suppress') continue;
+        if (disposition === 'warn') {
+          warnings.push(issue);
+          continue;
+        }
+        failures.push(issue);
+      }
+    }
+  }
+  return { failures, warnings };
+}
+
+// ============================================================================
+// The issue-based verify envelope
+// ============================================================================
+
+export interface VerifySqlSchemaByDiffInput {
+  readonly contract: Contract<SqlStorage>;
+  readonly schema: SqlSchemaIRNode;
+  readonly strict: boolean;
+  readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
+  /** The target's full-tree node diff (`diffSchema` descriptor hook). */
+  readonly diffSchema: SqlSchemaDiffFn;
+  /** The target's classifier: a diff issue node's `nodeKind` → its subject granularity. */
+  readonly granularityOf: (nodeKind: string) => DiffSubjectGranularity;
+}
+
+/**
+ * THE SQL schema verify: runs the target's full-tree node diff, grades it
+ * through the family's post-diff filters (strict gating + control-policy
+ * disposition) plus the codec `verifyType` hook findings, and wraps the
+ * verdict in the issue-based result envelope. `ok` holds exactly when both
+ * issue lists are empty — the lists carry the verdict's failures.
+ */
+export function verifySqlSchemaByDiff(
+  input: VerifySqlSchemaByDiffInput,
+): VerifyDatabaseSchemaResult {
+  const startTime = Date.now();
+  const verdictDiff = input.diffSchema({
+    contract: input.contract,
+    schema: input.schema,
+    frameworkComponents: input.frameworkComponents,
+  });
+  const diffVerdict = computeSqlDiffVerdict({
+    issues: verdictDiff.issues,
+    resolveControlPolicy: verdictDiff.resolveControlPolicy,
+    strict: input.strict,
+    defaultControlPolicy: input.contract.defaultControlPolicy,
+    granularityOf: input.granularityOf,
+  });
+  const storageTypeVerdict = computeStorageTypeVerdict({
+    contract: input.contract,
+    namespacePairs: verdictDiff.namespacePairs,
+    codecHooks: extractCodecControlHooks(input.frameworkComponents),
+  });
+  const failCount = diffVerdict.failures.length + storageTypeVerdict.failures.length;
+  const ok = failCount === 0;
+  const profileHash =
+    'profileHash' in input.contract && typeof input.contract.profileHash === 'string'
+      ? input.contract.profileHash
+      : undefined;
+  return {
+    ok,
+    ...(ok ? {} : { code: 'PN-SCHEMA-0001' }),
+    summary: ok
+      ? 'Database schema satisfies contract'
+      : `Database schema does not satisfy contract (${failCount} failure${failCount === 1 ? '' : 's'})`,
+    contract: {
+      storageHash: input.contract.storage.storageHash,
+      ...ifDefined('profileHash', profileHash),
+    },
+    target: {
+      expected: input.contract.target,
+      actual: input.contract.target,
+    },
+    schema: {
+      issues: [...diffVerdict.failures, ...storageTypeVerdict.failures],
+      warnings: {
+        issues: [...diffVerdict.warnings, ...storageTypeVerdict.warnings],
+      },
+    },
+    meta: { strict: input.strict },
+    timings: { total: Date.now() - startTime },
+  };
+}

package/src/core/diff/sql-schema-diff.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared relational-diff types and helpers. The coordinate-based issue diff
+ * this module used to house (`collectSqlSchemaIssues` /
+ * `collectSqlSchemaIssuesPerNamespace`) retired once the migration planner
+ * took `plan(start, end)` over the one differ (`buildPostgresPlanDiff` /
+ * `buildSqlitePlanDiff`); what remains here is consumed by the surviving
+ * verify verdict (`schema-verify.ts`) and the control adapters.
+ */
+
+import type { ColumnDefault } from '@prisma-next/contract/types';
+
+/**
+ * Function type for normalizing raw database default expressions into ColumnDefault.
+ * Target-specific implementations handle database dialect differences.
+ */
+export type DefaultNormalizer = (
+  rawDefault: string,
+  nativeType: string,
+) => ColumnDefault | undefined;
+
+/**
+ * Function type for normalizing schema native types to canonical form for comparison.
+ * Target-specific implementations handle dialect-specific type name variations
+ * (e.g., Postgres 'varchar' → 'character varying', 'timestamptz' normalization).
+ */
+export type NativeTypeNormalizer = (nativeType: string) => string;
+
+/**
+ * Compares two arrays of strings for equality (order-sensitive).
+ */
+export function arraysEqual(a: readonly string[], b: readonly string[]): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) {
+      return false;
+    }
+  }
+  return true;
+}

package/src/core/diff/verifier-disposition.ts

@@ -0,0 +1,30 @@
+import type { ControlPolicy } from '@prisma-next/contract/types';
+import type {
+  SchemaDiffIssue,
+  VerifierIssueCategory,
+  VerifierOutcome,
+} from '@prisma-next/framework-components/control';
+import { dispositionForCategory } from '@prisma-next/framework-components/control';
+
+/**
+ * Classifies a codec `verifyType` hook finding into the target-neutral
+ * categories the framework grades. A storage type is a named type instance
+ * (e.g. a native enum); the only shape divergence it can carry is a change
+ * to its value set, so a paired mismatch always classifies as `valueDrift`.
+ */
+export function classifyStorageTypeDiffIssue(issue: SchemaDiffIssue): VerifierIssueCategory {
+  if (issue.reason === 'not-found') {
+    return 'declaredMissing';
+  }
+  if (issue.reason === 'not-expected') {
+    return 'extraAuxiliary';
+  }
+  return 'valueDrift';
+}
+
+export function verifierDisposition(
+  controlPolicy: ControlPolicy,
+  issue: SchemaDiffIssue,
+): VerifierOutcome {
+  return dispositionForCategory(controlPolicy, classifyStorageTypeDiffIssue(issue));
+}

package/src/core/ir/sql-contract-serializer-base.ts

@@ -6,18 +6,15 @@ import {
   type AnyEntityKindDescriptor,
   hydrateNamespaceEntities,
   type Namespace,
-  NamespaceBase,
-  UNBOUND_NAMESPACE_ID,
 } from '@prisma-next/framework-components/ir';
 import { sqlContractCanonicalizationHooks } from '@prisma-next/sql-contract/canonicalization-hooks';
 import { composeSqlEntityKinds } from '@prisma-next/sql-contract/entity-kinds';
 import {
-  buildSqlNamespace,
-  type SqlNamespaceTablesInput,
+  isMaterializedSqlNamespace,
+  type SqlNamespaceInput,
   SqlStorage,
   type SqlStorageInput,
   type SqlStorageTypeEntry,
-  SqlUnboundNamespace,
 } from '@prisma-next/sql-contract/types';
 import {
   createSqlContractSchema,
@@ -25,7 +22,7 @@ import {
 } from '@prisma-next/sql-contract/validators';
 import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
-import type { JsonObject } from '@prisma-next/utils/json';
+import type { JsonObject, JsonValue } from '@prisma-next/utils/json';
 import { type Type, type } from 'arktype';
 
 const NamespaceRawSchema = type({
@@ -120,77 +117,48 @@ export abstract class SqlContractSerializerBase<TContract extends Contract<SqlSt
         'structural',
       );
     }
-    const hydratedNamespaces = this.hydrateSqlNamespaceMap(rawNamespaces);
-    // Compatibility shim: production code that addresses `__unbound__` for table
-    // metadata lookups (collection-contract, query-plan-mutations, model-accessor,
-    // query-plan-meta, where-binding) uses optional chaining and tolerates absence,
-    // but runtime-qualification (TML-2605) has not yet landed cross-namespace table
-    // routing. Injecting the empty singleton here keeps helpers that augment the
-    // deserialized JSON (e.g. buildMixedPolyContract) working by providing a slot to
-    // write into. Once runtime-qualification routes table lookups by namespace, this
-    // shim should be removed.
-    //
-    // TML-2916: the shim only fires when the target's default namespace IS unbound
-    // (SQLite, Mongo). On Postgres (`defaultNamespaceId === 'public'`) injecting an
-    // empty `__unbound__` slot violates ADR 223 — un-namespaced PG models belong in
-    // `public`, not `__unbound__`.
-    const withInjectedUnbound =
-      this.defaultNamespaceId === UNBOUND_NAMESPACE_ID
-        ? {
-            ...hydratedNamespaces,
-            [UNBOUND_NAMESPACE_ID]:
-              hydratedNamespaces[UNBOUND_NAMESPACE_ID] ?? SqlUnboundNamespace.instance,
-          }
-        : hydratedNamespaces;
+    const hydratedNamespaces = this.hydrateSqlNamespaceMap(
+      blindCast<
+        Readonly<Record<string, Record<string, unknown>>>,
+        'parseSqlContractStructure validated raw JSON; namespace entries are plain objects, not SqlNamespace instances.'
+      >(rawNamespaces),
+    );
 
     return {
       ...validated,
       storage: new SqlStorage({
         storageHash: validated.storage.storageHash,
         ...ifDefined('types', hydratedTypes),
-        // Cast narrows the result of hydrateSqlNamespaceMap from the wider
-        // framework `Namespace` to the SQL-family `SqlNamespace`.
         namespaces: blindCast<
           SqlStorageInput['namespaces'],
-          'hydrateSqlNamespaceMap builds each namespace through the SQL family concretions (SqlBoundNamespace / target schema), so every value is a SqlNamespace; the framework return type only promises the base Namespace.'
-        >(withInjectedUnbound),
+          'hydrateSqlNamespaceMap builds each namespace through the target serializer override, so every value is a SqlNamespace; the framework return type only promises the base Namespace.'
+        >(hydratedNamespaces),
       }),
     };
   }
 
-  protected abstract get defaultNamespaceId(): string;
-
   protected hydrateSqlNamespaceMap(
-    namespaces: Readonly<Record<string, Namespace | Record<string, unknown>>>,
+    namespaces: Readonly<Record<string, Record<string, unknown>>>,
   ): Readonly<Record<string, Namespace>> {
     return Object.fromEntries(
       Object.entries(namespaces).map(([nsId, namespaceEntryRaw]) => {
-        // Raw entries passed structural validation; hydrate materialises family IR class instances.
         const namespaceHydrated = this.hydrateSqlNamespaceEntry(nsId, namespaceEntryRaw);
-        const namespaceMaterialised =
-          namespaceHydrated instanceof NamespaceBase
-            ? namespaceHydrated
-            : buildSqlNamespace(
-                blindCast<
-                  SqlNamespaceTablesInput,
-                  'hydrateSqlNamespaceEntry returns SqlNamespaceTablesInput when raw is not a NamespaceBase'
-                >(namespaceHydrated),
-              );
-        return [nsId, namespaceMaterialised];
+        if (!isMaterializedSqlNamespace(namespaceHydrated)) {
+          throw new Error(
+            `Target serializer bug: hydrateSqlNamespaceEntry for namespace "${nsId}" returned a non-NamespaceBase value. Override hydrateSqlNamespaceEntry to produce a target namespace concretion.`,
+          );
+        }
+        return [nsId, namespaceHydrated];
       }),
     );
   }
 
   protected hydrateSqlNamespaceEntry(
     nsId: string,
-    raw: Namespace | Record<string, unknown>,
-  ): Namespace | SqlNamespaceTablesInput {
-    if (raw instanceof NamespaceBase) {
-      return raw;
-    }
-    const rawRecord = isPlainRecord(raw) ? raw : {};
-    const id = typeof rawRecord['id'] === 'string' ? rawRecord['id'] : nsId;
-    const parsed = NamespaceRawSchema({ ...rawRecord, id });
+    raw: Record<string, unknown>,
+  ): Namespace | SqlNamespaceInput {
+    const id = typeof raw['id'] === 'string' ? raw['id'] : nsId;
+    const parsed = NamespaceRawSchema({ ...raw, id });
     if (parsed instanceof type.errors) {
       const messages = parsed.map((p: { message: string }) => p.message).join('; ');
       throw new ContractValidationError(`Namespace hydration failed: ${messages}`, 'structural');
@@ -211,8 +179,8 @@ export abstract class SqlContractSerializerBase<TContract extends Contract<SqlSt
     }
 
     return blindCast<
-      SqlNamespaceTablesInput,
-      'entriesOutput holds the hydrated SQL entity-kind maps (table always present); this wraps them as the SqlNamespaceTablesInput the family createNamespace consumes.'
+      SqlNamespaceInput,
+      'entriesOutput holds the hydrated SQL entity-kind maps (table always present); this wraps them as the SqlNamespaceInput the target createNamespace consumes.'
     >({
       id,
       entries: entriesOutput,
@@ -240,4 +208,50 @@ export abstract class SqlContractSerializerBase<TContract extends Contract<SqlSt
   protected constructTargetContract(hydrated: Contract<SqlStorage>): TContract {
     return hydrated as TContract;
   }
+
+  /**
+   * Serializes a namespace's `entries` dict by walking every enumerable
+   * kind — no kind is named here, mirroring the generic hydrate walk in
+   * `hydrateSqlNamespaceEntry` above. `table` is the SQL family's one
+   * universal base kind (every namespace carries it), so it is always
+   * emitted, even when empty; every other kind — target- or
+   * pack-contributed — is emitted only when it holds at least one entry.
+   * A kind carried non-enumerable on `entries` is excluded here for free,
+   * since `Object.entries` honors enumerability.
+   */
+  protected serializeNamespaceEntries(
+    entries: Readonly<Record<string, Readonly<Record<string, unknown>>>>,
+  ): Record<string, Record<string, JsonObject>> {
+    const out: Record<string, Record<string, JsonObject>> = {
+      table: this.serializeEntries(entries['table'] ?? {}),
+    };
+    for (const [kind, record] of Object.entries(entries)) {
+      if (kind === 'table' || record == null || Object.keys(record).length === 0) {
+        continue;
+      }
+      out[kind] = this.serializeEntries(record);
+    }
+    return out;
+  }
+
+  private serializeEntries(entries: Readonly<Record<string, unknown>>): Record<string, JsonObject> {
+    const out: Record<string, JsonObject> = {};
+    for (const [name, entry] of Object.entries(entries)) {
+      out[name] = this.serializeJsonObject(entry);
+    }
+    return out;
+  }
+
+  protected serializeJsonObject(value: unknown): JsonObject {
+    return blindCast<
+      JsonObject,
+      'serializeJsonValue round-trips an IR node through JSON, yielding a JsonObject'
+    >(this.serializeJsonValue(value));
+  }
+
+  private serializeJsonValue(value: unknown): JsonValue {
+    return blindCast<JsonValue, 'JSON.parse(JSON.stringify(x)) yields a JsonValue'>(
+      JSON.parse(JSON.stringify(value)),
+    );
+  }
 }

package/src/core/ir/sql-contract-serializer.ts

@@ -1,5 +1,4 @@
 import type { Contract } from '@prisma-next/contract/types';
-import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import { SqlContractSerializerBase } from './sql-contract-serializer-base';
 
@@ -11,15 +10,14 @@ import { SqlContractSerializerBase } from './sql-contract-serializer-base';
  * codec-typed envelope wire a target-specific subclass with a populated
  * registry (see Postgres). Family-level call sites instantiate this
  * default directly when no target serializer is supplied.
+ *
+ * Because this serializer has no target concretion, deserialization of
+ * contracts that include namespace entries from JSON will throw unless
+ * the caller provides pre-hydrated `NamespaceBase` instances. Production
+ * paths always supply a target-specific serializer.
  */
 export class SqlContractSerializer extends SqlContractSerializerBase<Contract<SqlStorage>> {
   constructor() {
     super(new Map());
   }
-
-  // Family-level fallback when no target descriptor is wired in. Preserves the
-  // pre-TML-2916 compatibility-shim behaviour for the unbound slot.
-  protected override get defaultNamespaceId(): string {
-    return UNBOUND_NAMESPACE_ID;
-  }
 }

package/src/core/ir/sql-schema-verifier-base.ts

@@ -1,5 +1,5 @@
 import type {
-  SchemaIssue,
+  SchemaDiffIssue,
   SchemaVerifier,
   SchemaVerifyOptions,
   SchemaVerifyResult,
@@ -9,7 +9,7 @@ import type {
  * SQL family `SchemaVerifier` abstract base. Centralises the SQL-shared
  * walk (table-by-table + column-by-column matching keyed by
  * `(namespace.id, name)`, FK / unique / index comparisons via the
- * existing helpers in `verify-helpers.ts`) and exposes a protected hook
+ * shared satisfaction helpers in `sql-schema-diff.ts`) and exposes a protected hook
  * for target extensions (Postgres functions, RLS policies, future
  * target-only kinds).
  *
@@ -29,7 +29,7 @@ export abstract class SqlSchemaVerifierBase<TContract, TSchema>
   implements SchemaVerifier<TContract, TSchema>
 {
   verifySchema(options: SchemaVerifyOptions<TContract, TSchema>): SchemaVerifyResult {
-    const issues: SchemaIssue[] = [];
+    const issues: SchemaDiffIssue[] = [];
     issues.push(...this.verifyCommonSqlSchema(options));
     issues.push(...this.verifyTargetExtensions(options));
     return { ok: issues.length === 0, issues };
@@ -43,7 +43,7 @@ export abstract class SqlSchemaVerifierBase<TContract, TSchema>
    */
   protected abstract verifyCommonSqlSchema(
     options: SchemaVerifyOptions<TContract, TSchema>,
-  ): readonly SchemaIssue[];
+  ): readonly SchemaDiffIssue[];
 
   /**
    * Target-specific extensions — e.g. Postgres functions, future RLS
@@ -52,5 +52,5 @@ export abstract class SqlSchemaVerifierBase<TContract, TSchema>
    */
   protected abstract verifyTargetExtensions(
     options: SchemaVerifyOptions<TContract, TSchema>,
-  ): readonly SchemaIssue[];
+  ): readonly SchemaDiffIssue[];
 }