TML-2727: migrate migration aggregate to elementCoordinates (#629)

Author: wmadden

packages/1-framework/0-foundation/contract/src/exports/types.ts

@@ -45,7 +45,9 @@ export type {
   ProfileHashBase,
   Source,
   StorageBase,
+  StorageEntitySlot,
   StorageHashBase,
+  StorageNamespace,
 } from '../types';
 export {
   coreHash,

packages/1-framework/0-foundation/contract/src/types.ts

@@ -48,13 +48,34 @@ export function profileHash<const T extends string>(value: T): ProfileHashBase<T
   return value as ProfileHashBase<T>;
 }
 
+/**
+ * One entity-kind slot in a namespace — a map of entity name to entry.
+ * Values are opaque at the foundation layer; family and target concretions
+ * refine them to typed IR classes.
+ */
+export type StorageEntitySlot = Readonly<Record<string, unknown>>;
+
+/**
+ * Plain-data namespace entry in a storage block. Every hydrated contract
+ * carries at least `id` plus zero or more entity-kind slot maps (`tables`,
+ * `collections`, …). Foundation declares only this shape — no IR machinery.
+ */
+export interface StorageNamespace {
+  readonly id: string;
+}
+
 /**
  * Base type for family-specific storage blocks.
  * Family storage types (SqlStorage, MongoStorage, etc.) extend this to carry the
  * storage hash alongside family-specific data (tables, collections, etc.).
+ *
+ * The `namespaces` map is carried by every hydrated storage block. Serialized
+ * envelope shape is target-owned; this types the in-memory contract after
+ * `deserializeContract`.
  */
 export interface StorageBase<THash extends string = string> {
   readonly storageHash: StorageHashBase<THash>;
+  readonly namespaces: Readonly<Record<string, StorageNamespace>>;
 }
 
 export interface FieldType {

packages/1-framework/0-foundation/contract/test/canonicalization.test.ts

@@ -58,7 +58,7 @@ function minimal(overrides?: Record<string, unknown>): Contract {
     target: 'postgres',
     roots: {},
     models: {},
-    storage: { storageHash: coreHash('sha256:stub') },
+    storage: { storageHash: coreHash('sha256:stub'), namespaces: {} },
     extensionPacks: {},
     capabilities: {},
     meta: {},
@@ -131,7 +131,7 @@ describe('canonicalizeContractToObject', () => {
 
   it('includes storageHash when provided inside storage', () => {
     const result = canonicalizeContractToObject(
-      minimal({ storage: { storageHash: 'sha256:abc' } }),
+      minimal({ storage: { storageHash: 'sha256:abc', namespaces: {} } }),
     );
     expect(drill(result, 'storage')['storageHash']).toBe('sha256:abc');
   });
@@ -142,7 +142,9 @@ describe('canonicalizeContractToObject', () => {
   });
 
   it('keeps storageHash inside storage', () => {
-    const result = canonicalizeContractToObject(minimal({ storage: { storageHash: 'sha256:s' } }));
+    const result = canonicalizeContractToObject(
+      minimal({ storage: { storageHash: 'sha256:s', namespaces: {} } }),
+    );
     expect(result).not.toHaveProperty('storageHash');
     expect(drill(result, 'storage')['storageHash']).toBe('sha256:s');
   });
@@ -471,7 +473,7 @@ describe('index and unique sorting', () => {
 
   it('handles storage without namespaces (no-op)', () => {
     const result = canonicalizeContractToObject(
-      minimal({ storage: { storageHash: 'sha256:stub' } }),
+      minimal({ storage: { storageHash: 'sha256:stub', namespaces: {} } }),
     );
     expect(result['storage']).toBeDefined();
   });
@@ -597,7 +599,7 @@ describe('canonicalizeContract', () => {
 
   it('produces identical output as JSON.stringify of canonicalizeContractToObject', () => {
     const input = minimal({
-      storage: { storageHash: 'sha256:test' },
+      storage: { storageHash: 'sha256:test', namespaces: {} },
       profileHash: 'sha256:profile',
     });
     const objResult = canonicalizeContractToObject(input);
@@ -684,7 +686,11 @@ describe('typeParams preservation', () => {
   it('strips empty storage.types[].typeParams without shouldPreserveEmpty hook', () => {
     const result = canonicalizeContractToObject(
       minimal({
-        storage: { storageHash: 'sha256:stub', types: { MyType: { typeParams: {} } } },
+        storage: {
+          storageHash: 'sha256:stub',
+          namespaces: {},
+          types: { MyType: { typeParams: {} } },
+        },
       }),
     );
     const myType = drill(result, 'storage', 'types', 'MyType');

packages/1-framework/0-foundation/contract/test/contract-factories.test.ts

@@ -49,7 +49,7 @@ describe('createContract', () => {
 
   it('computes different storageHash for different storage', () => {
     const c1 = createContract({ storage: { namespaces: {} } });
-    const c2 = createContract({
+    const c2 = createSqlContract({
       storage: {
         namespaces: {
           public: { id: 'public', tables: { user: { columns: {} } } },

packages/1-framework/0-foundation/contract/test/contract-types.test-d.ts

@@ -47,6 +47,7 @@ type ExampleModels = {
 };
 
 type ExampleStorage = StorageBase<'sha256:abc123'> & {
+  readonly namespaces: Record<string, never>;
   readonly tables: {
     readonly user: {
       readonly columns: {

packages/1-framework/0-foundation/contract/test/contract-types.test.ts

@@ -28,7 +28,7 @@ describe('unified contract types', () => {
   describe('StorageBase', () => {
     it('carries branded storageHash', () => {
       const hash = 'sha256:abc123' as StorageHashBase<'sha256:abc123'>;
-      const storage = { storageHash: hash };
+      const storage = { storageHash: hash, namespaces: {} };
       expect(storage.storageHash).toBe('sha256:abc123');
     });
   });
@@ -48,7 +48,7 @@ describe('unified contract types', () => {
             storage: {},
           },
         },
-        storage: { storageHash: hash },
+        storage: { storageHash: hash, namespaces: {} },
         capabilities: {},
         extensionPacks: {},
         meta: {},
@@ -67,7 +67,7 @@ describe('unified contract types', () => {
         targetFamily: 'sql',
         roots: {},
         models: {},
-        storage: { storageHash: hash },
+        storage: { storageHash: hash, namespaces: {} },
         capabilities: {},
         extensionPacks: {},
         meta: {},
@@ -107,7 +107,7 @@ describe('unified contract types', () => {
             storage: {},
           },
         },
-        storage: { storageHash: hash },
+        storage: { storageHash: hash, namespaces: {} },
         capabilities: {},
         extensionPacks: {},
         meta: {},

packages/1-framework/1-core/framework-components/src/ir/namespace.ts

@@ -1,3 +1,4 @@
+import type { StorageNamespace } from '@prisma-next/contract/types';
 import { type IRNode, IRNodeBase } from './ir-node';
 
 /**
@@ -57,8 +58,7 @@ export const UNBOUND_NAMESPACE_ID = '__unbound__' as const;
  * on this invariant to enumerate entities structurally without
  * family-specific knowledge.
  */
-export interface Namespace extends IRNode {
-  readonly id: string;
+export interface Namespace extends IRNode, StorageNamespace {
   readonly kind: string;
 }
 

packages/1-framework/1-core/framework-components/src/ir/storage.ts

@@ -1,3 +1,4 @@
+import type { StorageBase } from '@prisma-next/contract/types';
 import type { IRNode } from './ir-node';
 import type { Namespace } from './namespace';
 
@@ -36,7 +37,9 @@ export interface EntityCoordinate {
  * property whose value is a non-null object, yields one coordinate per
  * entry key in that map. No family-specific slot vocabulary is required.
  */
-export function* elementCoordinates(storage: Storage): Generator<EntityCoordinate> {
+export function* elementCoordinates(
+  storage: Pick<StorageBase, 'namespaces'>,
+): Generator<EntityCoordinate> {
   for (const [namespaceId, ns] of Object.entries(storage.namespaces)) {
     for (const [entityKind, slot] of Object.entries(ns)) {
       if (entityKind === 'id') continue;

packages/1-framework/1-core/framework-components/test/element-coordinates.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { type EntityCoordinate, elementCoordinates, type Storage } from '../src/ir/storage';
+import { type EntityCoordinate, elementCoordinates } from '../src/ir/storage';
 
 function assertStoragePlaneCoordinates(coordinates: EntityCoordinate[]): void {
   expect(coordinates.length).toBeGreaterThan(0);
@@ -32,7 +32,7 @@ describe('elementCoordinates', () => {
           tables: { users: {}, posts: {}, comments: {} },
         },
       },
-    } as Storage;
+    };
 
     const coordinates = [...elementCoordinates(storage)];
     assertStoragePlaneCoordinates(coordinates);

packages/1-framework/3-tooling/cli/test/commands/cross-consumer-integrity.test.ts

@@ -159,7 +159,7 @@ async function writeContract(cwd: string, storageHash: string): Promise<void> {
   await writeFile(
     join(contractDir, 'contract.json'),
     JSON.stringify({
-      storage: { storageHash },
+      storage: { storageHash, namespaces: {} },
       schemaVersion: SCHEMA_VERSION,
       target: TARGET,
       targetFamily: TARGET_FAMILY,
@@ -190,7 +190,7 @@ async function writeCleanOrphanSpace(cwd: string, spaceId: string, hash: string)
   await writeFile(
     join(spaceDir, 'contract.json'),
     JSON.stringify({
-      storage: { storageHash: hash },
+      storage: { storageHash: hash, namespaces: {} },
       schemaVersion: SCHEMA_VERSION,
       target: TARGET,
       targetFamily: TARGET_FAMILY,
@@ -307,7 +307,7 @@ async function setupExtSpaceCorruptionFixture(): Promise<{ cwd: string; extId: s
   await writeFile(
     join(extDir, 'contract.json'),
     JSON.stringify({
-      storage: { storageHash: HASH_C },
+      storage: { storageHash: HASH_C, namespaces: {} },
       schemaVersion: SCHEMA_VERSION,
       target: TARGET,
       targetFamily: TARGET_FAMILY,