@prisma-next/family-sql 0.14.0-dev.4 → 0.14.0-dev.40

package/src/core/{schema-verify/verify-sql-schema.ts → diff/sql-schema-diff.ts}

@@ -24,8 +24,9 @@ import {
   StorageTable,
   type StorageTypeInstance,
 } from '@prisma-next/sql-contract/types';
-import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
+import type { SqlSchemaIR, SqlSchemaIRNode } from '@prisma-next/sql-schema-ir/types';
 import { canonicalStringify } from '@prisma-next/utils/canonical-stringify';
+import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { extractCodecControlHooks } from '../assembly';
 import { resolveValueSetValues } from '../migrations/contract-to-schema-ir';
@@ -42,6 +43,30 @@ import {
   verifyUniqueConstraints,
 } from './verify-helpers';
 
+/**
+ * Returns the per-schema namespace nodes of an introspected schema node, for
+ * the relational verify to consume one at a time. Structure-agnostic — imports
+ * no target node class. A root exposing a `namespaces` record (Postgres) yields
+ * its namespace nodes (never merged, so same-named tables in different schemas
+ * cannot collide); a flat schema (SQLite) is its own single namespace and
+ * yields itself. Handles spread-flattened input (own-enumerable fields survive).
+ */
+function namespaceSchemaNodes(schema: SqlSchemaIRNode): readonly SqlSchemaIR[] {
+  const obj = blindCast<
+    { readonly namespaces?: Readonly<Record<string, SqlSchemaIR>> },
+    'structural read of an own-enumerable namespaces record; survives the projectSchemaToSpace spread'
+  >(schema);
+  if (obj.namespaces !== undefined) {
+    return Object.values(obj.namespaces);
+  }
+  return [
+    blindCast<
+      SqlSchemaIR,
+      'a flat schema node (no namespaces) is its own single namespace, exposing the per-schema { tables } shape'
+    >(schema),
+  ];
+}
+
 /**
  * Function type for normalizing raw database default expressions into ColumnDefault.
  * Target-specific implementations handle database dialect differences.
@@ -89,6 +114,15 @@ export interface VerifySqlSchemaOptions {
    * with contract native types (e.g., Postgres 'varchar' → 'character varying').
    */
   readonly normalizeNativeType?: NativeTypeNormalizer;
+  /**
+   * When set, only the contract tables in these namespace ids are checked
+   * against `schema` (the matching actual namespace node). The full contract is
+   * still consulted for cross-namespace value-set / control-policy resolution.
+   * Used by the multi-schema verify, which pairs each contract namespace to its
+   * own actual node. Absent ⇒ all contract namespaces are checked against the
+   * single (flat) `schema` — the single-schema / SQLite path.
+   */
+  readonly restrictToNamespaceIds?: ReadonlySet<string>;
 }
 
 /**
@@ -128,6 +162,7 @@ export function verifySqlSchema(options: VerifySqlSchemaOptions): VerifyDatabase
     storageTypes,
     ...ifDefined('normalizeDefault', normalizeDefault),
     ...ifDefined('normalizeNativeType', normalizeNativeType),
+    ...ifDefined('restrictToNamespaceIds', options.restrictToNamespaceIds),
   });
 
   validateFrameworkComponentsForExtensions(contract, options.frameworkComponents);
@@ -236,6 +271,7 @@ export function verifySqlSchema(options: VerifySqlSchemaOptions): VerifyDatabase
     },
     schema: {
       issues,
+      schemaDiffIssues: [],
       root,
       counts,
     },
@@ -274,6 +310,7 @@ function verifySchemaTables(options: {
   storageTypes: Readonly<Record<string, StorageTypeInstance>>;
   normalizeDefault?: DefaultNormalizer;
   normalizeNativeType?: NativeTypeNormalizer;
+  restrictToNamespaceIds?: ReadonlySet<string>;
 }): { issues: SchemaIssue[]; rootChildren: SchemaVerificationNode[] } {
   const {
     contract,
@@ -284,6 +321,7 @@ function verifySchemaTables(options: {
     storageTypes,
     normalizeDefault,
     normalizeNativeType,
+    restrictToNamespaceIds,
   } = options;
   const contractDefaultControl = contract.defaultControlPolicy;
   const issues: SchemaIssue[] = [];
@@ -294,14 +332,17 @@ function verifySchemaTables(options: {
   );
 
   for (const namespaceId of namespaceIds) {
+    // When the caller pairs each contract namespace to its own actual node, it
+    // restricts the table check to that namespace; the full contract is still
+    // consulted for value-set / control-policy resolution.
+    if (restrictToNamespaceIds !== undefined && !restrictToNamespaceIds.has(namespaceId)) continue;
     const ns = contract.storage.namespaces[namespaceId];
     if (!ns) continue;
     for (const [tableName, contractTableRaw] of Object.entries(ns.entries.table ?? {})) {
-      if (!(contractTableRaw instanceof StorageTable)) {
-        throw new Error(
-          `verifySqlSchema: expected StorageTable at storage.namespaces.${namespaceId}.entries.table.${tableName}`,
-        );
-      }
+      StorageTable.assert(
+        contractTableRaw,
+        `storage.namespaces.${namespaceId}.entries.table.${tableName}`,
+      );
       const contractTable = contractTableRaw;
       const tableControlPolicy = effectiveControlPolicy(
         contractTable.control,
@@ -313,6 +354,7 @@ function verifySchemaTables(options: {
       if (!schemaTable) {
         const issue: SchemaIssue = {
           kind: 'missing_table',
+          reason: 'not-found',
           table: tableName,
           namespaceId,
           message: `Table "${tableName}" is missing from database`,
@@ -367,6 +409,7 @@ function verifySchemaTables(options: {
         const extraTableControlPolicy = effectiveControlPolicy(undefined, contractDefaultControl);
         const issue: SchemaIssue = {
           kind: 'extra_table',
+          reason: 'not-expected',
           table: tableName,
           message: `Extra table "${tableName}" found in database (not in contract)`,
         };
@@ -383,6 +426,7 @@ function verifySchemaTables(options: {
             expected: undefined,
             actual: undefined,
             children: [],
+            reason: 'not-expected',
           },
           issues,
           rootChildren,
@@ -507,6 +551,7 @@ function verifyTableChildren(options: {
   } else if (schemaTable.primaryKey && strict) {
     const issue: SchemaIssue = {
       kind: 'extra_primary_key',
+      reason: 'not-expected',
       table: tableName,
       namespaceId,
       message: 'Extra primary key found in database (not in contract)',
@@ -650,6 +695,7 @@ function collectContractColumnNodes(options: {
     if (!schemaColumn) {
       const issue: SchemaIssue = {
         kind: 'missing_column',
+        reason: 'not-found',
         table: tableName,
         namespaceId,
         column: columnName,
@@ -722,6 +768,7 @@ function appendExtraColumnNodes(options: {
     if (!contractTable.columns[columnName]) {
       const issue: SchemaIssue = {
         kind: 'extra_column',
+        reason: 'not-expected',
         table: tableName,
         namespaceId,
         column: columnName,
@@ -790,14 +837,16 @@ function verifyColumn(options: {
     tableName,
     columnName,
   });
-  const schemaNativeType =
+  const schemaBaseNativeType =
     normalizeNativeType?.(schemaColumn.nativeType) ?? schemaColumn.nativeType;
+  const schemaNativeType = schemaColumn.many ? `${schemaBaseNativeType}[]` : schemaBaseNativeType;
 
   const typesMatch = contractNativeType === schemaNativeType;
 
   if (!typesMatch) {
     const issue: SchemaIssue = {
       kind: 'type_mismatch',
+      reason: 'not-equal',
       table: tableName,
       namespaceId,
       column: columnName,
@@ -858,6 +907,7 @@ function verifyColumn(options: {
   if (contractColumn.nullable !== schemaColumn.nullable) {
     const issue: SchemaIssue = {
       kind: 'nullability_mismatch',
+      reason: 'not-equal',
       table: tableName,
       namespaceId,
       column: columnName,
@@ -888,6 +938,7 @@ function verifyColumn(options: {
       const defaultDescription = describeColumnDefault(contractColumn.default);
       const issue: SchemaIssue = {
         kind: 'default_missing',
+        reason: 'not-found',
         table: tableName,
         namespaceId,
         column: columnName,
@@ -922,6 +973,7 @@ function verifyColumn(options: {
       const actualDescription = schemaColumn.default;
       const issue: SchemaIssue = {
         kind: 'default_mismatch',
+        reason: 'not-equal',
         table: tableName,
         namespaceId,
         column: columnName,
@@ -949,6 +1001,7 @@ function verifyColumn(options: {
   } else if (strict && schemaColumn.default) {
     const issue: SchemaIssue = {
       kind: 'extra_default',
+      reason: 'not-expected',
       table: tableName,
       namespaceId,
       column: columnName,
@@ -1144,19 +1197,20 @@ function renderExpectedNativeType(
     context,
   );
 
+  let baseType: string;
+
   // If no typeParams or codecId, return the base native type
   if (!typeParams || !codecId) {
-    return nativeType;
+    baseType = nativeType;
+  } else {
+    // Try to use the codec's expandNativeType hook if available
+    const hooks = codecHooks.get(codecId);
+    baseType = hooks?.expandNativeType
+      ? hooks.expandNativeType({ nativeType, codecId, typeParams })
+      : nativeType;
   }
 
-  // Try to use the codec's expandNativeType hook if available
-  const hooks = codecHooks.get(codecId);
-  if (hooks?.expandNativeType) {
-    return hooks.expandNativeType({ nativeType, codecId, typeParams });
-  }
-
-  // Fallback: return base native type if no hook is available
-  return nativeType;
+  return contractColumn.many ? `${baseType}[]` : baseType;
 }
 
 function resolveContractColumnTypeMetadata(
@@ -1309,3 +1363,141 @@ function formatLiteralValue(value: unknown): string {
   }
   return JSON.stringify(value);
 }
+
+/**
+ * Reads a namespace node's DDL schema name. Namespaced target nodes (Postgres
+ * `PostgresNamespaceSchemaNode`) carry `schemaName`; a flat schema (SQLite) has
+ * none and pairs by position as the sole namespace.
+ */
+function namespaceSchemaName(node: SqlSchemaIR): string | undefined {
+  return blindCast<
+    { readonly schemaName?: string },
+    'reading the optional namespace schemaName off a per-schema node'
+  >(node).schemaName;
+}
+
+/**
+ * Returns a shallow copy of `contract` exposing only the one named namespace —
+ * used solely to resolve that namespace's live DDL schema via the target's
+ * expected-tree projection (never for verification, so global value-sets it may
+ * reference are not consulted).
+ */
+function scopeContractToNamespace(
+  contract: Contract<SqlStorage>,
+  namespaceId: string,
+): Contract<SqlStorage> {
+  const namespace = contract.storage.namespaces[namespaceId];
+  const scopedNamespaces = namespace === undefined ? {} : { [namespaceId]: namespace };
+  return blindCast<
+    Contract<SqlStorage>,
+    'narrowing storage.namespaces to one entry; the rest of the contract is preserved'
+  >({
+    ...contract,
+    storage: blindCast<
+      SqlStorage,
+      'shallow storage copy with a single-namespace map; other storage fields are preserved'
+    >({
+      ...contract.storage,
+      namespaces: scopedNamespaces,
+    }),
+  });
+}
+
+/**
+ * Combines two `VerifyDatabaseSchemaResult`s by concatenating issues and summing
+ * counts — used to fold the per-namespace pairings of a multi-schema database
+ * into one result. The verification-tree `root` of the first pairing is
+ * retained (multi-schema verify-tree shaping is future work).
+ */
+function mergeVerifyResults(
+  a: VerifyDatabaseSchemaResult,
+  b: VerifyDatabaseSchemaResult,
+): VerifyDatabaseSchemaResult {
+  return {
+    ...a,
+    ok: a.ok && b.ok,
+    ...ifDefined('code', a.code ?? b.code),
+    schema: {
+      ...a.schema,
+      issues: [...a.schema.issues, ...b.schema.issues],
+      schemaDiffIssues: [...a.schema.schemaDiffIssues, ...b.schema.schemaDiffIssues],
+      counts: {
+        pass: a.schema.counts.pass + b.schema.counts.pass,
+        warn: a.schema.counts.warn + b.schema.counts.warn,
+        fail: a.schema.counts.fail + b.schema.counts.fail,
+        totalNodes: a.schema.counts.totalNodes + b.schema.counts.totalNodes,
+      },
+    },
+  };
+}
+
+/**
+ * The single per-namespace-paired relational verify shared by the migration
+ * planner and the family schema verify — there is exactly one such operation.
+ *
+ * Each contract namespace is paired to the introspected namespace node holding
+ * the same DDL schema, then `verifySqlSchema` checks that namespace's tables
+ * against the matching actual node (a contract table under `auth` is only ever
+ * looked up in the `auth` actual node, so a multi-schema database no longer
+ * reports tables in other schemas as missing). The full contract is passed every
+ * time — `restrictToNamespaceIds` scopes only which tables are checked, so
+ * cross-namespace value-set / control-policy resolution is unaffected.
+ *
+ * The DDL schema of each contract namespace is read from a single-namespace
+ * expected projection (`buildExpectedSchema`), which both callers already build
+ * the same way. Empty contract namespaces verify nothing and are skipped.
+ * Single-schema (one namespace) and SQLite's flat schema are one pairing —
+ * byte-identical to the prior per-node verify.
+ */
+export function verifySqlSchemaTree(options: {
+  readonly contract: Contract<SqlStorage>;
+  readonly actualSchema: SqlSchemaIRNode;
+  readonly buildExpectedSchema: (contract: Contract<SqlStorage>) => SqlSchemaIRNode;
+  readonly strict: boolean;
+  readonly typeMetadataRegistry: ReadonlyMap<string, { nativeType?: string }>;
+  readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
+  readonly normalizeDefault?: DefaultNormalizer;
+  readonly normalizeNativeType?: NativeTypeNormalizer;
+}): VerifyDatabaseSchemaResult {
+  const baseOptions = {
+    contract: options.contract,
+    strict: options.strict,
+    typeMetadataRegistry: options.typeMetadataRegistry,
+    frameworkComponents: options.frameworkComponents,
+    ...ifDefined('normalizeDefault', options.normalizeDefault),
+    ...ifDefined('normalizeNativeType', options.normalizeNativeType),
+  };
+
+  const actualNodes = namespaceSchemaNodes(options.actualSchema);
+  const actualByName = new Map<string, SqlSchemaIR>();
+  for (const node of actualNodes) {
+    const name = namespaceSchemaName(node);
+    if (name !== undefined) actualByName.set(name, node);
+  }
+  // A flat actual schema (SQLite) has no named namespaces — it is the sole node.
+  const soleFlatActual = actualByName.size === 0 ? actualNodes[0] : undefined;
+  const emptyNamespace: SqlSchemaIR = { tables: {} };
+
+  let combined: VerifyDatabaseSchemaResult | undefined;
+  for (const namespaceId of Object.keys(options.contract.storage.namespaces)) {
+    const namespace = options.contract.storage.namespaces[namespaceId];
+    if (!namespace || Object.keys(namespace.entries.table ?? {}).length === 0) continue;
+
+    const ddlSchema = namespaceSchemaNodes(
+      options.buildExpectedSchema(scopeContractToNamespace(options.contract, namespaceId)),
+    )
+      .map(namespaceSchemaName)
+      .find((name) => name !== undefined);
+    const actualNode =
+      (ddlSchema !== undefined ? actualByName.get(ddlSchema) : soleFlatActual) ?? emptyNamespace;
+
+    const result = verifySqlSchema({
+      ...baseOptions,
+      schema: actualNode,
+      restrictToNamespaceIds: new Set([namespaceId]),
+    });
+    combined = combined === undefined ? result : mergeVerifyResults(combined, result);
+  }
+
+  return combined ?? verifySqlSchema({ ...baseOptions, schema: emptyNamespace });
+}

package/src/core/{schema-verify → diff}/verify-helpers.ts

@@ -151,6 +151,7 @@ export function verifyPrimaryKey(
   if (!schemaPK) {
     const issue: SchemaIssue = {
       kind: 'primary_key_mismatch',
+      reason: 'not-equal',
       table: tableName,
       namespaceId,
       expected: contractPK.columns.join(', '),
@@ -163,6 +164,7 @@ export function verifyPrimaryKey(
   if (!arraysEqual(contractPK.columns, schemaPK.columns)) {
     const issue: SchemaIssue = {
       kind: 'primary_key_mismatch',
+      reason: 'not-equal',
       table: tableName,
       namespaceId,
       expected: contractPK.columns.join(', '),
@@ -220,6 +222,7 @@ export function verifyForeignKeys(
     if (!matchingFK) {
       const issue: SchemaIssue = {
         kind: 'foreign_key_mismatch',
+        reason: 'not-equal',
         table: tableName,
         namespaceId,
         expected: `${contractFK.source.columns.join(', ')} -> ${contractFK.target.tableName}(${contractFK.target.columns.join(', ')})`,
@@ -250,6 +253,7 @@ export function verifyForeignKeys(
         const combinedActual = actionMismatches.map((m) => m.actual).join(', ');
         const issue: SchemaIssue = {
           kind: 'foreign_key_mismatch',
+          reason: 'not-equal',
           table: tableName,
           namespaceId,
           indexOrConstraint: matchingFK.name ?? `fk(${contractFK.source.columns.join(',')})`,
@@ -309,6 +313,7 @@ export function verifyForeignKeys(
       if (!matchingFK) {
         const issue: SchemaIssue = {
           kind: 'extra_foreign_key',
+          reason: 'not-expected',
           table: tableName,
           namespaceId,
           indexOrConstraint: schemaFK.name ?? `fk(${schemaFK.columns.join(',')})`,
@@ -379,6 +384,7 @@ export function verifyUniqueConstraints(
     if (!matchingUnique && !matchingUniqueIndex) {
       const issue: SchemaIssue = {
         kind: 'unique_constraint_mismatch',
+        reason: 'not-equal',
         table: tableName,
         namespaceId,
         expected: contractUnique.columns.join(', '),
@@ -425,6 +431,7 @@ export function verifyUniqueConstraints(
       if (!matchingUnique) {
         const issue: SchemaIssue = {
           kind: 'extra_unique_constraint',
+          reason: 'not-expected',
           table: tableName,
           namespaceId,
           indexOrConstraint: schemaUnique.name ?? `unique(${schemaUnique.columns.join(',')})`,
@@ -501,6 +508,7 @@ export function verifyIndexes(
     if (!matchingIndex && !matchingUniqueConstraint) {
       const issue: SchemaIssue = {
         kind: 'index_mismatch',
+        reason: 'not-equal',
         table: tableName,
         namespaceId,
         expected: contractIndex.columns.join(', '),
@@ -552,6 +560,7 @@ export function verifyIndexes(
       if (!matchingIndex) {
         const issue: SchemaIssue = {
           kind: 'extra_index',
+          reason: 'not-expected',
           table: tableName,
           namespaceId,
           indexOrConstraint: schemaIndex.name ?? `idx(${schemaIndex.columns.join(',')})`,
@@ -718,6 +727,7 @@ export function verifyCheckConstraints(
     if (!liveCheck) {
       const issue: SchemaIssue = {
         kind: 'check_missing',
+        reason: 'not-found',
         table: tableName,
         namespaceId,
         indexOrConstraint: contractCheck.name,
@@ -744,6 +754,7 @@ export function verifyCheckConstraints(
     } else if (!valueSetsEqual(contractCheck.permittedValues, liveCheck.permittedValues)) {
       const issue: SchemaIssue = {
         kind: 'check_mismatch',
+        reason: 'not-equal',
         table: tableName,
         namespaceId,
         indexOrConstraint: contractCheck.name,
@@ -789,6 +800,7 @@ export function verifyCheckConstraints(
       if (!matchingContract) {
         const issue: SchemaIssue = {
           kind: 'check_removed',
+          reason: 'not-equal',
           table: tableName,
           namespaceId,
           indexOrConstraint: liveCheck.name,

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,
@@ -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,

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;
-  }
 }