TML-2727: address PR #630 review on namespace construction

Rename bound namespace concretions to SqlBoundNamespace / MongoBoundNamespace
with static factories, discriminate map entries by family kind instead of
instanceof, brand __unbound__ on SqlStorageInput, and use ifDefined at
hydration boundaries.

Signed-off-by: wmadden-electric <286902546+wmadden-electric@users.noreply.github.com>

Author: wmadden-electric

packages/2-mongo-family/1-foundation/mongo-contract/src/ir/build-mongo-namespace.ts

@@ -9,13 +9,36 @@ import { MongoCollection } from './mongo-collection';
 import type { MongoNamespace, MongoNamespaceCollectionsInput } from './mongo-storage';
 import { MongoUnboundNamespace } from './mongo-unbound-namespace';
 
-class MongoNamespaceFromCollectionsInput extends NamespaceBase {
+const MONGO_NAMESPACE_KIND = 'mongo-namespace' as const;
+
+function isMaterializedMongoNamespace(
+  ns: Namespace | MongoNamespaceCollectionsInput,
+): ns is MongoNamespace {
+  if (typeof ns !== 'object' || ns === null) {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(ns);
+  if (proto === Object.prototype || proto === null) {
+    return false;
+  }
+  return (ns as Namespace).kind === MONGO_NAMESPACE_KIND;
+}
+
+class MongoBoundNamespace extends NamespaceBase {
   declare readonly kind: string;
 
   readonly id: string;
   readonly collections: Readonly<Record<string, MongoCollection>>;
 
-  constructor(input: MongoNamespaceCollectionsInput) {
+  static fromCollectionsInput(input: MongoNamespaceCollectionsInput): MongoNamespace {
+    const collectionCount = Object.keys(input.collections ?? {}).length;
+    if (input.id === UNBOUND_NAMESPACE_ID && collectionCount === 0) {
+      return castAs<MongoNamespace>(MongoUnboundNamespace.instance);
+    }
+    return castAs<MongoNamespace>(new MongoBoundNamespace(input));
+  }
+
+  private constructor(input: MongoNamespaceCollectionsInput) {
     super();
     this.id = input.id;
     this.collections = Object.freeze(
@@ -27,7 +50,7 @@ class MongoNamespaceFromCollectionsInput extends NamespaceBase {
       ),
     );
     Object.defineProperty(this, 'kind', {
-      value: 'mongo-namespace',
+      value: MONGO_NAMESPACE_KIND,
       writable: false,
       enumerable: false,
       configurable: true,
@@ -37,11 +60,7 @@ class MongoNamespaceFromCollectionsInput extends NamespaceBase {
 }
 
 export function buildMongoNamespace(input: MongoNamespaceCollectionsInput): MongoNamespace {
-  const collectionCount = Object.keys(input.collections ?? {}).length;
-  if (input.id === UNBOUND_NAMESPACE_ID && collectionCount === 0) {
-    return castAs<MongoNamespace>(MongoUnboundNamespace.instance);
-  }
-  return castAs<MongoNamespace>(new MongoNamespaceFromCollectionsInput(input));
+  return MongoBoundNamespace.fromCollectionsInput(input);
 }
 
 export function buildMongoNamespaceMap(
@@ -50,12 +69,12 @@ export function buildMongoNamespaceMap(
   return Object.fromEntries(
     Object.entries(namespaces).map(([nsKey, ns]) => [
       nsKey,
-      ns instanceof NamespaceBase
+      isMaterializedMongoNamespace(ns)
         ? blindCast<
             MongoNamespace,
-            'an already-built NamespaceBase in a Mongo-family namespace map is a MongoNamespace'
+            'a materialised Mongo-family namespace entry in a namespace map is a MongoNamespace'
           >(ns)
-        : buildMongoNamespace(ns),
+        : MongoBoundNamespace.fromCollectionsInput(ns),
     ]),
   );
 }

packages/2-sql/1-core/contract/src/ir/build-sql-namespace.ts

@@ -10,14 +10,36 @@ import type { SqlNamespace, SqlNamespaceTablesInput } from './sql-storage';
 import { SqlUnboundNamespace } from './sql-unbound-namespace';
 import { StorageTable } from './storage-table';
 
-class SqlNamespaceFromTablesInput extends NamespaceBase {
+const SQL_NAMESPACE_KIND = 'sql-namespace' as const;
+
+function isMaterializedSqlNamespace(ns: Namespace | SqlNamespaceTablesInput): ns is SqlNamespace {
+  if (typeof ns !== 'object' || ns === null) {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(ns);
+  if (proto === Object.prototype || proto === null) {
+    return false;
+  }
+  return (ns as Namespace).kind === SQL_NAMESPACE_KIND;
+}
+
+class SqlBoundNamespace extends NamespaceBase {
   declare readonly kind: string;
   declare readonly enum?: Readonly<Record<string, PostgresEnumStorageEntry>>;
 
   readonly id: string;
   readonly tables: Readonly<Record<string, StorageTable>>;
 
-  constructor(input: SqlNamespaceTablesInput) {
+  static fromTablesInput(input: SqlNamespaceTablesInput): SqlNamespace {
+    const tableCount = Object.keys(input.tables ?? {}).length;
+    const enumCount = Object.keys(input.enum ?? {}).length;
+    if (input.id === UNBOUND_NAMESPACE_ID && tableCount === 0 && enumCount === 0) {
+      return castAs<SqlNamespace>(SqlUnboundNamespace.instance);
+    }
+    return castAs<SqlNamespace>(new SqlBoundNamespace(input));
+  }
+
+  private constructor(input: SqlNamespaceTablesInput) {
     super();
     this.id = input.id;
     this.tables = Object.freeze(
@@ -37,7 +59,7 @@ class SqlNamespaceFromTablesInput extends NamespaceBase {
       });
     }
     Object.defineProperty(this, 'kind', {
-      value: 'sql-namespace',
+      value: SQL_NAMESPACE_KIND,
       writable: false,
       enumerable: false,
       configurable: true,
@@ -47,12 +69,7 @@ class SqlNamespaceFromTablesInput extends NamespaceBase {
 }
 
 export function buildSqlNamespace(input: SqlNamespaceTablesInput): SqlNamespace {
-  const tableCount = Object.keys(input.tables ?? {}).length;
-  const enumCount = Object.keys(input.enum ?? {}).length;
-  if (input.id === UNBOUND_NAMESPACE_ID && tableCount === 0 && enumCount === 0) {
-    return castAs<SqlNamespace>(SqlUnboundNamespace.instance);
-  }
-  return castAs<SqlNamespace>(new SqlNamespaceFromTablesInput(input));
+  return SqlBoundNamespace.fromTablesInput(input);
 }
 
 export function buildSqlNamespaceMap(
@@ -61,12 +78,12 @@ export function buildSqlNamespaceMap(
   return Object.fromEntries(
     Object.entries(namespaces).map(([nsKey, ns]) => [
       nsKey,
-      ns instanceof NamespaceBase
+      isMaterializedSqlNamespace(ns)
         ? blindCast<
             SqlNamespace,
-            'an already-built NamespaceBase in an SQL-family namespace map is a SqlNamespace'
+            'a materialised SQL-family namespace entry in a namespace map is a SqlNamespace'
           >(ns)
-        : buildSqlNamespace(ns),
+        : SqlBoundNamespace.fromTablesInput(ns),
     ]),
   );
 }

packages/2-sql/1-core/contract/src/ir/sql-storage.ts

@@ -32,7 +32,9 @@ export interface SqlNamespaceTablesInput {
 export interface SqlStorageInput<THash extends string = string> {
   readonly storageHash: StorageHashBase<THash>;
   readonly types?: Record<string, SqlStorageTypeEntry>;
-  readonly namespaces: Readonly<Record<string, Namespace>>;
+  readonly namespaces: Readonly<Record<string, SqlNamespace>> & {
+    readonly __unbound__: SqlNamespace;
+  };
 }
 
 /**
@@ -81,9 +83,7 @@ export class SqlStorage<THash extends string = string> extends SqlNode implement
   constructor(input: SqlStorageInput<THash>) {
     super();
     this.storageHash = input.storageHash;
-    this.namespaces = Object.freeze(input.namespaces) as Readonly<Record<string, SqlNamespace>> & {
-      readonly __unbound__: SqlNamespace;
-    };
+    this.namespaces = Object.freeze(input.namespaces);
     if (input.types !== undefined) {
       this.types = Object.freeze(
         Object.fromEntries(

packages/2-sql/1-core/contract/src/validators.ts

@@ -7,6 +7,8 @@ import {
 } from '@prisma-next/contract/types';
 import { validateContractDomain } from '@prisma-next/contract/validate-domain';
 import type { Namespace } from '@prisma-next/framework-components/ir';
+import { blindCast } from '@prisma-next/utils/casts';
+import { ifDefined } from '@prisma-next/utils/defined';
 import { type Type, type } from 'arktype';
 import { buildSqlNamespaceMap } from './ir/build-sql-namespace';
 import {
@@ -448,8 +450,11 @@ export function validateStorage(value: unknown): SqlStorage {
   };
   return new SqlStorage({
     storageHash: validated.storageHash,
-    ...(validated.types !== undefined ? { types: validated.types } : {}),
-    namespaces: buildSqlNamespaceMap(validated.namespaces ?? {}),
+    ...ifDefined('types', validated.types),
+    namespaces: blindCast<
+      SqlStorageInput['namespaces'],
+      'structural storage validation requires the __unbound__ namespace slot'
+    >(buildSqlNamespaceMap(validated.namespaces ?? {})),
   });
 }
 

packages/2-sql/1-core/contract/test/build-sql-namespace-map.test.ts

@@ -0,0 +1,29 @@
+import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
+import { describe, expect, it } from 'vitest';
+import { buildSqlNamespace, buildSqlNamespaceMap } from '../src/ir/build-sql-namespace';
+import { SqlUnboundNamespace } from '../src/ir/sql-unbound-namespace';
+
+const emptyTableInput = {
+  columns: {},
+  uniques: [],
+  indexes: [],
+  foreignKeys: [],
+} as const;
+
+describe('buildSqlNamespaceMap', () => {
+  it('passes through a materialised namespace without re-wrapping tables', () => {
+    const built = buildSqlNamespace({ id: 'app', tables: { users: emptyTableInput } });
+    const map = buildSqlNamespaceMap({ app: built });
+    expect(map.app).toBe(built);
+  });
+
+  it('materialises plain tables-input entries', () => {
+    const map = buildSqlNamespaceMap({
+      [UNBOUND_NAMESPACE_ID]: { id: UNBOUND_NAMESPACE_ID },
+      app: { id: 'app', tables: { users: emptyTableInput } },
+    });
+    expect(map[UNBOUND_NAMESPACE_ID]).toBe(SqlUnboundNamespace.instance);
+    expect(map.app.id).toBe('app');
+    expect(map.app.tables.users).toBeDefined();
+  });
+});

packages/2-sql/2-authoring/contract-ts/src/build-contract.ts

@@ -21,7 +21,7 @@ import {
 } from '@prisma-next/contract/types';
 import { type CapabilityMatrix, mergeCapabilityMatrices } from '@prisma-next/contract-authoring';
 import type { CodecLookup } from '@prisma-next/framework-components/codec';
-import { type Namespace, UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
+import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
 import { validateIndexTypes } from '@prisma-next/sql-contract/index-type-validation';
 import {
   createIndexTypeRegistry,
@@ -35,13 +35,15 @@ import {
   type PostgresEnumStorageEntry,
   type SqlNamespaceTablesInput,
   SqlStorage,
+  type SqlStorageInput,
   type StorageColumn,
   StorageTable,
   type StorageTableInput,
   type StorageTypeInstance,
   toStorageTypeInstance,
 } from '@prisma-next/sql-contract/types';
 import { validateStorageSemantics } from '@prisma-next/sql-contract/validators';
+import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
 import type {
   ContractDefinition,
@@ -544,16 +546,21 @@ export function buildSqlContractFromDefinition(
     namespaceCoordinateIds.add(id);
   }
   const { createNamespace } = definition;
-  const namespaces: Record<string, Namespace> = Object.fromEntries(
-    [...namespaceCoordinateIds].sort().map((id) => {
-      const enumTypes = namespaceEnumTypesById[id];
-      const nsInput: SqlNamespaceTablesInput = {
-        id,
-        tables: tablesByNamespace[id] ?? {},
-        ...ifDefined('enum', enumTypes),
-      };
-      return [id, createNamespace ? createNamespace(nsInput) : buildSqlNamespace(nsInput)];
-    }),
+  const namespaces = blindCast<
+    SqlStorageInput['namespaces'],
+    'contract authoring always materialises the __unbound__ namespace coordinate'
+  >(
+    Object.fromEntries(
+      [...namespaceCoordinateIds].sort().map((id) => {
+        const enumTypes = namespaceEnumTypesById[id];
+        const nsInput: SqlNamespaceTablesInput = {
+          id,
+          tables: tablesByNamespace[id] ?? {},
+          ...ifDefined('enum', enumTypes),
+        };
+        return [id, createNamespace ? createNamespace(nsInput) : buildSqlNamespace(nsInput)];
+      }),
+    ),
   );
   const domainUnboundTypes =
     Object.keys(documentTypes).length > 0 ? { types: documentTypes } : undefined;

packages/2-sql/5-runtime/test/utils.ts

@@ -422,9 +422,7 @@ export function createTestContract(
       ? new SqlStorage({
           ...rest['storage'],
           storageHash: storageHashValue,
-          namespaces:
-            rest['storage'].namespaces ??
-            ({ __unbound__: SqlUnboundNamespace.instance } as SqlStorageInput['namespaces']),
+          namespaces: rest['storage'].namespaces ?? { __unbound__: SqlUnboundNamespace.instance },
         })
       : new SqlStorage({
           storageHash: storageHashValue,

packages/2-sql/9-family/src/core/ir/sql-contract-serializer-base.ts

@@ -6,6 +6,7 @@ import {
   buildSqlNamespace,
   type SqlNamespaceTablesInput,
   SqlStorage,
+  type SqlStorageInput,
   type SqlStorageTypeEntry,
   StorageTable,
   type StorageTableInput,
@@ -14,6 +15,8 @@ import {
   createSqlContractSchema,
   validateSqlContractFully,
 } 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 Type, type } from 'arktype';
 
@@ -115,8 +118,11 @@ export abstract class SqlContractSerializerBase<TContract extends Contract<SqlSt
       ...validated,
       storage: new SqlStorage({
         storageHash: validated.storage.storageHash,
-        ...(hydratedTypes !== undefined ? { types: hydratedTypes } : {}),
-        namespaces: hydratedNamespaces,
+        ...ifDefined('types', hydratedTypes),
+        namespaces: blindCast<
+          SqlStorageInput['namespaces'],
+          'deserialized SQL contracts require the __unbound__ namespace slot'
+        >(hydratedNamespaces),
       }),
     };
   }
@@ -125,9 +131,14 @@ export abstract class SqlContractSerializerBase<TContract extends Contract<SqlSt
     namespaces: Readonly<Record<string, Namespace | Record<string, unknown>>>,
   ): Readonly<Record<string, Namespace>> {
     return Object.fromEntries(
-      Object.entries(namespaces).map(([nsId, raw]) => {
-        const hydrated = this.hydrateSqlNamespaceEntry(nsId, raw);
-        return [nsId, hydrated instanceof NamespaceBase ? hydrated : buildSqlNamespace(hydrated)];
+      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(namespaceHydrated);
+        return [nsId, namespaceMaterialised];
       }),
     );
   }

packages/3-extensions/pgvector/test/migrations/planner.behavior.test.ts

@@ -19,6 +19,7 @@ import {
 import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
 import { createPostgresMigrationPlanner } from '@prisma-next/target-postgres/planner';
 import { buildBuiltinIdentityValue } from '@prisma-next/target-postgres/planner-identity-values';
+import { blindCast } from '@prisma-next/utils/casts';
 import { describe, expect, it } from 'vitest';
 import pgvectorDescriptor from '../../src/exports/control';
 
@@ -580,14 +581,16 @@ function createTestContract(
     },
   };
   const { storage: _s, ...rest } = overrides ?? {};
-  const namespaces = storageInput.namespaces
-    ? buildSqlNamespaceMap(storageInput.namespaces)
-    : {
-        [UNBOUND_NAMESPACE_ID]: buildSqlNamespace({
-          id: UNBOUND_NAMESPACE_ID,
-          tables: defaultTables,
-        }),
-      };
+  const namespaces = blindCast<SqlStorageInput['namespaces']>(
+    storageInput.namespaces
+      ? buildSqlNamespaceMap(storageInput.namespaces)
+      : {
+          [UNBOUND_NAMESPACE_ID]: buildSqlNamespace({
+            id: UNBOUND_NAMESPACE_ID,
+            tables: defaultTables,
+          }),
+        },
+  );
   return {
     target: 'postgres',
     targetFamily: 'sql',