@domainlang/language 0.6.0 → 0.7.0

package/src/lsp/domain-lang-scope-provider.ts

@@ -0,0 +1,134 @@
+/**
+ * DomainLang Scope Provider
+ *
+ * Implements import-based scoping for the DomainLang DSL.
+ *
+ * **Key Concept:**
+ * Unlike languages with global namespaces, DomainLang enforces strict import-based scoping:
+ * - Elements are only visible if they are defined in the current document OR explicitly imported
+ * - The global scope is restricted to imported documents only
+ * - Transitive imports do NOT provide scope (only direct imports)
+ *
+ * **Why this matters:**
+ * Without this, Langium's DefaultScopeProvider would make ALL indexed documents visible
+ * in the global scope, which would:
+ * 1. Allow referencing elements that haven't been imported
+ * 2. Make the import system meaningless
+ * 3. Create confusion about dependencies between files
+ *
+ * @see https://langium.org/docs/recipes/scoping/ for Langium scoping patterns
+ */
+
+import type {
+    AstNodeDescription,
+    LangiumDocument,
+    ReferenceInfo,
+    Scope,
+    Stream
+} from 'langium';
+import {
+    AstUtils,
+    DefaultScopeProvider,
+    EMPTY_SCOPE,
+    MapScope
+} from 'langium';
+import type { DomainLangServices } from '../domain-lang-module.js';
+import type { DomainLangIndexManager } from './domain-lang-index-manager.js';
+
+/**
+ * Custom scope provider that restricts cross-file references to imported documents only.
+ *
+ * Extends Langium's DefaultScopeProvider to override the global scope computation.
+ */
+export class DomainLangScopeProvider extends DefaultScopeProvider {
+    /**
+     * Reference to IndexManager for getting resolved imports.
+     */
+    private readonly domainLangIndexManager: DomainLangIndexManager;
+
+    constructor(services: DomainLangServices) {
+        super(services);
+        this.domainLangIndexManager = services.shared.workspace.IndexManager as DomainLangIndexManager;
+    }
+
+    /**
+     * Override getGlobalScope to restrict it to imported documents only.
+     *
+     * The default Langium behavior includes ALL documents in the workspace.
+     * We restrict this to:
+     * 1. The current document's own exported symbols
+     * 2. Exported symbols from directly imported documents
+     *
+     * @param referenceType - The AST type being referenced
+     * @param context - Information about the reference
+     * @returns A scope containing only visible elements
+     */
+    protected override getGlobalScope(referenceType: string, context: ReferenceInfo): Scope {
+        const document = AstUtils.getDocument(context.container);
+        if (!document) {
+            return EMPTY_SCOPE;
+        }
+
+        // Get the set of URIs that are in scope for this document
+        const importedUris = this.getImportedDocumentUris(document);
+
+        // Filter the global index to only include descriptions from imported documents
+        const filteredDescriptions = this.filterDescriptionsByImports(
+            referenceType,
+            document,
+            importedUris
+        );
+
+        // Create a scope from the filtered descriptions
+        return new MapScope(filteredDescriptions);
+    }
+
+    /**
+     * Gets the set of document URIs that are directly imported by the given document.
+     *
+     * Uses the resolved imports tracked by DomainLangIndexManager during indexing.
+     * This ensures accurate resolution including path aliases.
+     *
+     * @param document - The document to get imports for
+     * @returns Set of imported document URIs (as strings)
+     */
+    private getImportedDocumentUris(document: LangiumDocument): Set<string> {
+        const docUri = document.uri.toString();
+
+        // Get resolved imports from the index manager (tracked during indexing)
+        const resolvedImports = this.domainLangIndexManager.getResolvedImports(docUri);
+
+        // Always include the current document itself
+        const importedUris = new Set<string>([docUri]);
+
+        // Add all resolved import URIs
+        for (const resolvedUri of resolvedImports) {
+            importedUris.add(resolvedUri);
+        }
+
+        return importedUris;
+    }
+
+    /**
+     * Filters the global index to only include descriptions from imported documents.
+     *
+     * @param referenceType - The AST type being referenced
+     * @param currentDocument - The document making the reference
+     * @param importedUris - Set of URIs that are in scope
+     * @returns Stream of filtered descriptions
+     */
+    private filterDescriptionsByImports(
+        referenceType: string,
+        currentDocument: LangiumDocument,
+        importedUris: Set<string>
+    ): Stream<AstNodeDescription> {
+        // Get all descriptions of the reference type from the index
+        const allDescriptions = this.indexManager.allElements(referenceType);
+
+        // Filter to only those from imported documents
+        return allDescriptions.filter(desc => {
+            const descDocUri = desc.documentUri.toString();
+            return importedUris.has(descDocUri);
+        });
+    }
+}

package/src/lsp/domain-lang-workspace-manager.ts

@@ -1,3 +1,5 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
 import { DefaultWorkspaceManager, URI, UriUtils, type FileSystemNode, type LangiumDocument, type LangiumSharedCoreServices, type WorkspaceFolder } from 'langium';
 import type { CancellationToken } from 'vscode-languageserver-protocol';
 import { ensureImportGraphFromDocument } from '../utils/import-utils.js';
@@ -74,9 +76,10 @@ export class DomainLangWorkspaceManager extends DefaultWorkspaceManager {
         // Find ALL model.yaml files in workspace (supports mixed mode)
         const manifestInfos = await this.findAllManifestsInFolders(folders);
         
-        if (manifestInfos.length === 0) {
-            return; // Pure Mode B: no manifests, all files loaded on-demand
-        }
+        // Track directories covered by manifests to avoid loading their files as standalone
+        const moduleDirectories = new Set(
+            manifestInfos.map(m => path.dirname(m.manifestPath))
+        );
 
         // Mode A or Mode C: Load each module's entry + import graph
         for (const manifestInfo of manifestInfos) {
@@ -111,6 +114,128 @@ export class DomainLangWorkspaceManager extends DefaultWorkspaceManager {
                 // Continue with other modules - partial failure is acceptable
             }
         }
+
+        // Load standalone .dlang files in workspace root folders
+        // These are files NOT covered by any module's import graph
+        await this.loadStandaloneFiles(folders, moduleDirectories, collector);
+    }
+
+    /**
+     * Loads standalone .dlang files from workspace folders recursively.
+     * 
+     * Skips:
+     * - Module directories (directories with model.yaml) - loaded via import graph
+     * - `.dlang/cache` directory - package cache managed by CLI
+     * 
+     * @param folders - Workspace folders to scan
+     * @param moduleDirectories - Set of directories containing model.yaml (to skip)
+     * @param collector - Document collector callback
+     */
+    private async loadStandaloneFiles(
+        folders: WorkspaceFolder[],
+        moduleDirectories: Set<string>,
+        collector: (document: LangiumDocument) => void
+    ): Promise<void> {
+        const standaloneDocs: LangiumDocument[] = [];
+
+        for (const folder of folders) {
+            const folderPath = URI.parse(folder.uri).fsPath;
+            const docs = await this.loadDlangFilesRecursively(folderPath, moduleDirectories, collector);
+            standaloneDocs.push(...docs);
+        }
+
+        // Build all standalone documents in batch for performance
+        if (standaloneDocs.length > 0) {
+            await this.sharedServices.workspace.DocumentBuilder.build(standaloneDocs, {
+                validation: true
+            });
+        }
+    }
+
+    /**
+     * Recursively loads .dlang files from a directory.
+     * Skips module directories and the .dlang/cache package cache.
+     */
+    private async loadDlangFilesRecursively(
+        dirPath: string,
+        moduleDirectories: Set<string>,
+        collector: (document: LangiumDocument) => void
+    ): Promise<LangiumDocument[]> {
+        // Skip module directories - they're loaded via import graph
+        if (moduleDirectories.has(dirPath)) {
+            return [];
+        }
+
+        // Skip .dlang/cache - package cache managed by CLI
+        const baseName = path.basename(dirPath);
+        const parentName = path.basename(path.dirname(dirPath));
+        if (baseName === 'cache' && parentName === '.dlang') {
+            return [];
+        }
+        // Also skip the .dlang directory itself if it contains cache
+        if (baseName === '.dlang') {
+            return [];
+        }
+
+        const docs: LangiumDocument[] = [];
+
+        try {
+            const entries = await fs.readdir(dirPath, { withFileTypes: true });
+            
+            for (const entry of entries) {
+                const entryPath = path.join(dirPath, entry.name);
+
+                if (entry.isDirectory()) {
+                    // Recurse into subdirectories
+                    const subDocs = await this.loadDlangFilesRecursively(entryPath, moduleDirectories, collector);
+                    docs.push(...subDocs);
+                } else if (this.isDlangFile(entry)) {
+                    const doc = await this.tryLoadDocument(dirPath, entry.name, collector);
+                    if (doc) {
+                        docs.push(doc);
+                    }
+                }
+            }
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`Failed to read directory ${dirPath}: ${message}`);
+        }
+
+        return docs;
+    }
+
+    /**
+     * Checks if a directory entry is a .dlang file.
+     */
+    private isDlangFile(entry: { isFile(): boolean; name: string }): boolean {
+        return entry.isFile() && entry.name.toLowerCase().endsWith('.dlang');
+    }
+
+    /**
+     * Attempts to load a document, returning undefined on failure.
+     */
+    private async tryLoadDocument(
+        folderPath: string,
+        fileName: string,
+        collector: (document: LangiumDocument) => void
+    ): Promise<LangiumDocument | undefined> {
+        const filePath = path.join(folderPath, fileName);
+        const uri = URI.file(filePath);
+        
+        // Skip if already loaded (e.g., through imports)
+        if (this.langiumDocuments.hasDocument(uri)) {
+            return undefined;
+        }
+
+        try {
+            const doc = await this.langiumDocuments.getOrCreateDocument(uri);
+            collector(doc);
+            return doc;
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`Failed to load standalone file ${filePath}: ${message}`);
+            return undefined;
+        }
     }
 
     /**

package/src/main.ts

@@ -40,7 +40,7 @@ shared.lsp.LanguageServer.onInitialize((params) => {
 // This invalidates caches when config files change externally
 shared.lsp.DocumentUpdateHandler?.onWatchedFilesChange(async (params) => {
     try {
-        await handleConfigFileChanges(params, DomainLang.imports.WorkspaceManager, shared);
+        await handleFileChanges(params, DomainLang.imports.WorkspaceManager, shared, DomainLang);
     } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         console.error(`Error handling file change notification: ${message}`);
@@ -48,41 +48,174 @@ shared.lsp.DocumentUpdateHandler?.onWatchedFilesChange(async (params) => {
     }
 });
 
+/** Categorized file changes */
+interface CategorizedChanges {
+    manifestChanged: boolean;
+    lockFileChanged: boolean;
+    changedDlangUris: Set<string>;
+    deletedDlangUris: Set<string>;
+    createdDlangUris: Set<string>;
+}
+
 /**
- * Handles changes to model.yaml and model.lock files.
- * Invalidates caches and rebuilds workspace as needed.
- * Uses incremental updates: only rebuilds if dependencies actually changed.
+ * Categorizes file changes by type.
  */
-async function handleConfigFileChanges(
+function categorizeChanges(
     params: { changes: Array<{ uri: string; type: number }> },
     workspaceManager: typeof DomainLang.imports.WorkspaceManager,
-    sharedServices: typeof shared
-): Promise<void> {
-    let manifestChanged = false;
-    let lockFileChanged = false;
+    langServices: typeof DomainLang,
+    indexManager: DomainLangIndexManager
+): CategorizedChanges {
+    const result: CategorizedChanges = {
+        manifestChanged: false,
+        lockFileChanged: false,
+        changedDlangUris: new Set(),
+        deletedDlangUris: new Set(),
+        createdDlangUris: new Set()
+    };
 
     for (const change of params.changes) {
         const uri = URI.parse(change.uri);
         const fileName = uri.path.split('/').pop() ?? '';
+        const uriString = change.uri;
 
         if (fileName === 'model.yaml') {
-            console.warn(`model.yaml changed: ${change.uri}`);
+            console.warn(`model.yaml changed: ${uriString}`);
             workspaceManager.invalidateManifestCache();
-            DomainLang.imports.ImportResolver.clearCache();
-            // Clear IndexManager import dependencies - resolved paths may have changed
-            const indexManager = sharedServices.workspace.IndexManager as DomainLangIndexManager;
+            langServices.imports.ImportResolver.clearCache();
             indexManager.clearImportDependencies();
-            manifestChanged = true;
+            result.manifestChanged = true;
         } else if (fileName === 'model.lock') {
-            await handleLockFileChange(change, workspaceManager);
-            DomainLang.imports.ImportResolver.clearCache();
-            lockFileChanged = true;
+            console.warn(`model.lock changed: ${uriString}`);
+            langServices.imports.ImportResolver.clearCache();
+            result.lockFileChanged = true;
+        } else if (fileName.endsWith('.dlang')) {
+            if (change.type === FileChangeType.Deleted) {
+                result.deletedDlangUris.add(uriString);
+                console.warn(`DomainLang file deleted: ${uriString}`);
+            } else if (change.type === FileChangeType.Created) {
+                result.createdDlangUris.add(uriString);
+                console.warn(`DomainLang file created: ${uriString}`);
+            } else {
+                result.changedDlangUris.add(uriString);
+                console.warn(`DomainLang file changed: ${uriString}`);
+            }
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Rebuilds documents that depend on changed/deleted/created .dlang files.
+ */
+async function rebuildAffectedDocuments(
+    changes: CategorizedChanges,
+    indexManager: DomainLangIndexManager,
+    sharedServices: typeof shared,
+    langServices: typeof DomainLang
+): Promise<void> {
+    const hasChanges = changes.changedDlangUris.size > 0 || 
+                       changes.deletedDlangUris.size > 0 || 
+                       changes.createdDlangUris.size > 0;
+    if (!hasChanges) {
+        return;
+    }
+
+    // CRITICAL: Clear ImportResolver cache BEFORE rebuilding.
+    // The WorkspaceCache only clears AFTER linking, but resolution happens
+    // DURING linking. Without this, stale cached resolutions would be used.
+    langServices.imports.ImportResolver.clearCache();
+
+    const affectedUris = collectAffectedDocuments(changes, indexManager);
+
+    if (affectedUris.size === 0) {
+        return;
+    }
+
+    console.warn(`Rebuilding ${affectedUris.size} documents affected by file changes`);
+
+    const langiumDocuments = sharedServices.workspace.LangiumDocuments;
+    const affectedDocs: URI[] = [];
+
+    for (const uriString of affectedUris) {
+        const uri = URI.parse(uriString);
+        if (langiumDocuments.hasDocument(uri)) {
+            affectedDocs.push(uri);
+            indexManager.markForReprocessing(uriString);
         }
     }
 
-    // Only rebuild if dependencies changed, not just any manifest change
-    if (manifestChanged || lockFileChanged) {
-        await rebuildWorkspace(sharedServices, workspaceManager, manifestChanged);
+    const deletedUriObjects = [...changes.deletedDlangUris].map(u => URI.parse(u));
+    if (affectedDocs.length > 0 || deletedUriObjects.length > 0) {
+        await sharedServices.workspace.DocumentBuilder.update(affectedDocs, deletedUriObjects);
+    }
+}
+
+/**
+ * Collects all document URIs that should be rebuilt based on the changes.
+ * 
+ * Uses targeted matching to avoid expensive full rebuilds:
+ * - For edits: rebuild documents that import the changed file (by resolved URI)
+ * - For all changes: rebuild documents whose import specifiers match the path
+ * 
+ * The specifier matching handles renamed/moved/created files by comparing
+ * import specifiers against path segments (filename, parent/filename, etc.).
+ */
+function collectAffectedDocuments(
+    changes: CategorizedChanges,
+    indexManager: DomainLangIndexManager
+): Set<string> {
+    const allChangedUris = new Set([
+        ...changes.changedDlangUris, 
+        ...changes.deletedDlangUris,
+        ...changes.createdDlangUris
+    ]);
+    
+    // Get documents affected by resolved URI changes (edits to imported files)
+    const affectedByUri = indexManager.getAllAffectedDocuments(allChangedUris);
+    
+    // Get documents with import specifiers that match changed paths
+    // This catches:
+    // - File moves/renames: specifiers that previously resolved but now won't
+    // - File creations: specifiers that previously failed but might now resolve
+    // Uses fuzzy matching on path segments rather than rebuilding all imports
+    const affectedBySpecifier = indexManager.getDocumentsWithPotentiallyAffectedImports(allChangedUris);
+    
+    return new Set([...affectedByUri, ...affectedBySpecifier]);
+}
+
+/**
+ * Handles all file changes including .dlang files, model.yaml, and model.lock.
+ * 
+ * For .dlang files: rebuilds all documents that import the changed file.
+ * For config files: invalidates caches and rebuilds workspace as needed.
+ */
+async function handleFileChanges(
+    params: { changes: Array<{ uri: string; type: number }> },
+    workspaceManager: typeof DomainLang.imports.WorkspaceManager,
+    sharedServices: typeof shared,
+    langServices: typeof DomainLang
+): Promise<void> {
+    const indexManager = sharedServices.workspace.IndexManager as DomainLangIndexManager;
+
+    // Categorize and process changes
+    const changes = categorizeChanges(params, workspaceManager, langServices, indexManager);
+
+    // Handle lock file changes
+    if (changes.lockFileChanged) {
+        const lockChange = params.changes.find(c => c.uri.endsWith('model.lock'));
+        if (lockChange) {
+            await handleLockFileChange(lockChange, workspaceManager);
+        }
+    }
+
+    // Rebuild documents affected by .dlang file changes
+    await rebuildAffectedDocuments(changes, indexManager, sharedServices, langServices);
+
+    // Handle config file changes
+    if (changes.manifestChanged || changes.lockFileChanged) {
+        await rebuildWorkspace(sharedServices, workspaceManager, changes.manifestChanged);
     }
 }
 
@@ -93,8 +226,6 @@ async function handleLockFileChange(
     change: { uri: string; type: number },
     workspaceManager: typeof DomainLang.imports.WorkspaceManager
 ): Promise<void> {
-    console.warn(`model.lock changed: ${change.uri}`);
-    
     if (change.type === FileChangeType.Changed || change.type === FileChangeType.Created) {
         await workspaceManager.refreshLockFile();
     } else if (change.type === FileChangeType.Deleted) {

package/src/services/import-resolver.ts

@@ -1,10 +1,16 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { URI, type LangiumDocument } from 'langium';
+import { DocumentState, SimpleCache, WorkspaceCache, URI, type LangiumDocument, type LangiumSharedCoreServices } from 'langium';
 import { WorkspaceManager } from './workspace-manager.js';
 import type { DomainLangServices } from '../domain-lang-module.js';
 import type { LockFile } from './types.js';
 
+/**
+ * Cache interface for import resolution.
+ * Uses WorkspaceCache in LSP mode (clears on ANY document change) or SimpleCache in standalone mode.
+ */
+type ResolverCache = WorkspaceCache<string, URI> | SimpleCache<string, URI>;
+
 /**
  * ImportResolver resolves import statements using manifest-centric rules (PRS-010).
  *
@@ -17,21 +23,66 @@ import type { LockFile } from './types.js';
  * - ./types → ./types/index.dlang → ./types.dlang
  * - Module entry defaults to index.dlang (no model.yaml required)
  * 
- * Performance:
- * - Resolution results are cached per (document URI + specifier) pair
- * - Cache is invalidated when model.yaml or model.lock changes
+ * Caching Strategy (uses Langium standard infrastructure):
+ * - LSP mode: Uses `WorkspaceCache` - clears on ANY document change in workspace
+ *   This is necessary because file moves/deletes affect resolution of OTHER documents
+ * - Standalone mode: Uses `SimpleCache` - manual invalidation via clearCache()
+ * 
+ * Why WorkspaceCache (not DocumentCache)?
+ * - DocumentCache only invalidates when the KEYED document changes
+ * - But import resolution can break when IMPORTED files are moved/deleted
+ * - Example: index.dlang imports @domains → domains/index.dlang
+ *   If domains/index.dlang is moved, index.dlang's cache entry must be cleared
+ *   DocumentCache wouldn't clear it (index.dlang didn't change)
+ *   WorkspaceCache clears on ANY change, ensuring correct re-resolution
+ * 
+ * @see https://langium.org/docs/recipes/caching/ for Langium caching patterns
  */
 export class ImportResolver {
     private readonly workspaceManager: WorkspaceManager;
-    private readonly resolverCache = new Map<string, URI>();
+    /**
+     * Workspace-level cache for resolved import URIs.
+     * In LSP mode: WorkspaceCache - clears when ANY document changes (correct for imports)
+     * In standalone mode: SimpleCache - manual invalidation via clearCache()
+     */
+    private readonly resolverCache: ResolverCache;
 
+    /**
+     * Creates an ImportResolver.
+     * 
+     * @param services - DomainLang services. If `services.shared` is present, uses WorkspaceCache
+     *                   for automatic invalidation. Otherwise uses SimpleCache for standalone mode.
+     */
     constructor(services: DomainLangServices) {
         this.workspaceManager = services.imports.WorkspaceManager;
+        
+        // Use Langium's WorkspaceCache when shared services are available (LSP mode)
+        // Fall back to SimpleCache for standalone utilities (SDK, CLI)
+        const shared = (services as DomainLangServices & { shared?: LangiumSharedCoreServices }).shared;
+        if (shared) {
+            // LSP mode: WorkspaceCache with DocumentState.Linked
+            // 
+            // This follows the standard pattern used by TypeScript, rust-analyzer, gopls:
+            // - Cache is valid for a "workspace snapshot"
+            // - Invalidates after a batch of changes completes linking (debounced ~300ms)
+            // - Invalidates immediately on file deletion
+            // - Does NOT invalidate during typing (would be too expensive)
+            //
+            // DocumentState.Linked is the right phase because:
+            // - Import resolution is needed during linking
+            // - By the time linking completes, we know which files exist
+            // - File renames appear as delete+create, triggering immediate invalidation
+            this.resolverCache = new WorkspaceCache(shared, DocumentState.Linked);
+        } else {
+            // Standalone mode: simple key-value cache, manual invalidation
+            this.resolverCache = new SimpleCache<string, URI>();
+        }
     }
 
     /**
-     * Clears the import resolution cache.
-     * Call this when model.yaml or model.lock changes.
+     * Clears the entire import resolution cache.
+     * In LSP mode, this is also triggered automatically by WorkspaceCache on any document change.
+     * Call explicitly when model.yaml or model.lock changes.
      */
     clearCache(): void {
         this.resolverCache.clear();
@@ -39,10 +90,10 @@ export class ImportResolver {
 
     /**
      * Resolve an import specifier relative to a Langium document.
-     * Results are cached for performance.
+     * Results are cached using WorkspaceCache (clears on any workspace change).
      */
     async resolveForDocument(document: LangiumDocument, specifier: string): Promise<URI> {
-        // Check cache first (key: document URI + specifier)
+        // Cache key combines document URI + specifier for uniqueness
         const cacheKey = `${document.uri.toString()}|${specifier}`;
         const cached = this.resolverCache.get(cacheKey);
         if (cached) {

package/src/validation/constants.ts

@@ -34,6 +34,7 @@ export const IssueCodes = {
     ImportMissingRef: 'import-missing-ref',
     ImportAbsolutePath: 'import-absolute-path',
     ImportEscapesWorkspace: 'import-escapes-workspace',
+    ImportUnresolved: 'import-unresolved',
     
     // Domain Issues
     DomainNoVision: 'domain-no-vision',
@@ -56,6 +57,9 @@ export const IssueCodes = {
     ContextMapNoRelationships: 'context-map-no-relationships',
     DomainMapNoDomains: 'domain-map-no-domains',
     
+    // Reference Issues
+    UnresolvedReference: 'unresolved-reference',
+    
     // Metadata Issues
     MetadataMissingName: 'metadata-missing-name',
     
@@ -262,6 +266,14 @@ export const ValidationMessages = {
         `Local path dependency '${alias}' escapes workspace boundary.\n` +
         `Hint: Local dependencies must be within the workspace. Consider moving the dependency or using a git-based source.`,
 
+    /**
+     * Error when import path cannot be resolved to a file.
+     * @param uri - The import URI that couldn't be resolved
+     */
+    IMPORT_UNRESOLVED: (uri: string) =>
+        `Cannot resolve import '${uri}'.\n` +
+        `Hint: Check that the file exists and the path is correct.`,
+
     // ========================================================================
     // Context Map & Domain Map Validation
     // ========================================================================
@@ -291,6 +303,18 @@ export const ValidationMessages = {
         `Domain Map '${name}' contains no domains.\n` +
         `Hint: Use 'contains DomainA, DomainB' to specify which domains are in the map.`,
 
+    // ========================================================================
+    // Reference Resolution Validation
+    // ========================================================================
+
+    /**
+     * Error when a reference cannot be resolved (for MultiReferences).
+     * @param type - The type being referenced (e.g., 'BoundedContext')
+     * @param name - The unresolved name
+     */
+    UNRESOLVED_REFERENCE: (type: string, name: string) =>
+        `Could not resolve reference to ${type} named '${name}'.`,
+
     // ========================================================================
     // Metadata Validation
     // ========================================================================