test: tighten contract-ts runtime guard typing

Author: jkomyno

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

@@ -171,7 +171,7 @@ function buildDomainField(
 export function buildSqlContractFromDefinition(
   definition: ContractDefinition,
   codecLookup?: CodecLookup,
-): Contract {
+): Contract<SqlStorage> {
   const target = definition.target.targetId;
   const targetFamily = 'sql';
   const modelsByName = new Map(definition.models.map((m) => [m.modelName, m]));

packages/2-sql/2-authoring/contract-ts/test/contract-builder.contract-definition.test.ts

@@ -1,3 +1,4 @@
+import type { CodecLookup } from '@prisma-next/framework-components/codec';
 import type { TargetPackRef } from '@prisma-next/framework-components/components';
 import { describe, expect, it } from 'vitest';
 import { buildSqlContractFromDefinition } from '../src/contract-builder';
@@ -175,6 +176,59 @@ describe('shared contract definition lowering', () => {
     });
   });
 
+  it('encodes literal defaults through codecLookup during storage lowering', () => {
+    const codecLookup: CodecLookup = {
+      get: (id) => {
+        if (id !== 'pg/timestamptz@1') {
+          return undefined;
+        }
+
+        return {
+          id,
+          targetTypes: ['timestamptz'],
+          traits: ['equality', 'order'] as const,
+          decode: (wire: unknown) => wire,
+          encodeJson: (value: unknown) =>
+            value instanceof Date ? value.toISOString() : (value as string),
+          decodeJson: (json: unknown) => new Date(json as string),
+        };
+      },
+    };
+
+    const contract = buildSqlContractFromDefinition(
+      {
+        target: postgresTargetPack,
+        models: [
+          {
+            modelName: 'Event',
+            tableName: 'event',
+            fields: [
+              {
+                fieldName: 'scheduledAt',
+                columnName: 'scheduled_at',
+                descriptor: {
+                  codecId: 'pg/timestamptz@1',
+                  nativeType: 'timestamptz',
+                },
+                nullable: false,
+                default: {
+                  kind: 'literal',
+                  value: new Date('2025-01-01T00:00:00.000Z'),
+                },
+              },
+            ],
+          },
+        ],
+      },
+      codecLookup,
+    );
+
+    expect(contract.storage.tables['event']?.columns['scheduled_at']?.default).toEqual({
+      kind: 'literal',
+      value: '2025-01-01T00:00:00.000Z',
+    });
+  });
+
   it('rejects generated fields that also declare storage defaults', () => {
     expect(() =>
       buildSqlContractFromDefinition({

packages/2-sql/2-authoring/contract-ts/test/contract-builder.entrypoint.test.ts

@@ -0,0 +1,111 @@
+import type {
+  ExtensionPackRef,
+  FamilyPackRef,
+  TargetPackRef,
+} from '@prisma-next/framework-components/components';
+import { describe, expect, it } from 'vitest';
+import { defineContract } from '../src/contract-builder';
+
+const sqlFamilyPack = {
+  kind: 'family',
+  id: 'sql',
+  familyId: 'sql',
+  version: '0.0.1',
+} as const satisfies FamilyPackRef<'sql'>;
+
+const documentFamilyPack = {
+  kind: 'family',
+  id: 'document',
+  familyId: 'document',
+  version: '0.0.1',
+} as const satisfies FamilyPackRef<'document'>;
+
+const postgresTargetPack = {
+  kind: 'target',
+  id: 'postgres',
+  familyId: 'sql',
+  targetId: 'postgres',
+  version: '0.0.1',
+} as const satisfies TargetPackRef<'sql', 'postgres'>;
+
+const pgvectorExtensionPack = {
+  kind: 'extension',
+  id: 'pgvector',
+  familyId: 'sql',
+  targetId: 'postgres',
+  version: '0.0.1',
+} as const satisfies ExtensionPackRef<'sql', 'postgres'>;
+
+const mysqlExtensionPack = {
+  ...pgvectorExtensionPack,
+  targetId: 'mysql',
+} as const satisfies ExtensionPackRef<'sql', 'mysql'>;
+
+function unsafeExtensionPackRefForRuntimeTest<FamilyId extends string, TargetId extends string>(
+  pack: FamilyPackRef<string> | TargetPackRef<string, string> | ExtensionPackRef<string, string>,
+): ExtensionPackRef<FamilyId, TargetId> {
+  // These runtime-guard tests intentionally bypass the static pack-ref contract so they can
+  // assert the error paths for invalid inputs that well-typed authoring code cannot produce.
+  return pack as unknown as ExtensionPackRef<FamilyId, TargetId>;
+}
+
+describe('defineContract runtime guards', () => {
+  it.each([
+    {
+      name: 'non-SQL family packs',
+      run: () =>
+        defineContract({
+          family: documentFamilyPack,
+          target: postgresTargetPack,
+          models: {},
+        }),
+      error: 'defineContract only accepts SQL family packs. Received family "document".',
+    },
+    {
+      name: 'non-extension pack refs in extensionPacks',
+      run: () =>
+        defineContract({
+          family: sqlFamilyPack,
+          target: postgresTargetPack,
+          extensionPacks: {
+            invalid: unsafeExtensionPackRefForRuntimeTest(postgresTargetPack),
+          },
+          models: {},
+        }),
+      error:
+        'defineContract only accepts extension pack refs in extensionPacks. Received kind "target".',
+    },
+    {
+      name: 'extension packs from another family',
+      run: () =>
+        defineContract({
+          family: sqlFamilyPack,
+          target: postgresTargetPack,
+          extensionPacks: {
+            invalid: unsafeExtensionPackRefForRuntimeTest({
+              ...pgvectorExtensionPack,
+              familyId: 'document',
+            }),
+          },
+          models: {},
+        }),
+      error:
+        'extension pack "pgvector" targets family "document" but contract target family is "sql".',
+    },
+    {
+      name: 'extension packs for another target',
+      run: () =>
+        defineContract({
+          family: sqlFamilyPack,
+          target: postgresTargetPack,
+          extensionPacks: {
+            invalid: mysqlExtensionPack,
+          },
+          models: {},
+        }),
+      error: 'extension pack "pgvector" targets "mysql" but contract target is "postgres".',
+    },
+  ])('rejects $name', ({ run, error }) => {
+    expect(run).toThrow(error);
+  });
+});