@kaelio/ktx 0.11.0 → 0.13.0

package/dist/context/sl/local-sl.js

@@ -1,54 +1,19 @@
 import { join } from 'node:path';
 import YAML from 'yaml';
 import { z } from 'zod';
+import { deriveFederatedConnection, FEDERATED_CONNECTION_ID } from '../connections/federation.js';
 import { HybridSearchCore } from '../../context/search/hybrid-search-core.js';
 import { DEFAULT_PRIORITY, resolveDescription } from './descriptions.js';
 import { normalizeSemanticLayerDescriptions } from './description-normalization.js';
 import { sourceDefinitionSchema, sourceOverlaySchema } from './schemas.js';
 import { composeOverlay, projectManifestEntry, SemanticLayerService, toResolvedWire, } from './semantic-layer.service.js';
 import { loadLatestSlDictionaryEntries } from './sl-dictionary-profile.js';
+import { assertSafeConnectionId, isSafeConnectionId, isSlYamlPath, slSourceNameForFile, sourceNameFromPath, } from './source-files.js';
 import { buildSemanticLayerSourceSearchText, SlSearchService } from './sl-search.service.js';
 import { SqliteSlSourcesIndex } from './sqlite-sl-sources-index.js';
-const LOCAL_AUTHOR = 'ktx';
-const LOCAL_AUTHOR_EMAIL = 'ktx@example.com';
-function assertSafePathToken(kind, value) {
-    if (value.trim().length === 0 ||
-        value.includes('..') ||
-        value.includes('\\') ||
-        value.startsWith('/') ||
-        value.startsWith('.') ||
-        value.includes('//')) {
-        throw new Error(`Unsafe ${kind}: ${value}`);
-    }
-    return value;
-}
-function assertSafeConnectionId(connectionId) {
-    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(connectionId)) {
-        throw new Error(`Unsafe connection id: ${connectionId}`);
-    }
-    return assertSafePathToken('connection id', connectionId);
-}
-function isSafeConnectionId(connectionId) {
-    return typeof connectionId === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(connectionId);
-}
-function assertSafeSourceName(sourceName) {
-    if (!/^[a-z0-9][a-z0-9_]*$/.test(sourceName)) {
-        throw new Error(`Unsafe semantic-layer source name: ${sourceName}`);
-    }
-    return assertSafePathToken('semantic-layer source name', sourceName);
-}
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-function slPath(connectionId, sourceName) {
-    return `semantic-layer/${assertSafeConnectionId(connectionId)}/${assertSafeSourceName(sourceName)}.yaml`;
-}
-function sourceNameFromPath(path) {
-    return (path
-        .split('/')
-        .at(-1)
-        ?.replace(/\.ya?ml$/, '') ?? path);
-}
 function parseYamlRecord(raw) {
     const parsed = YAML.parse(raw);
     if (!isRecord(parsed)) {
@@ -122,15 +87,46 @@ function parsedStandaloneSource(parsed, name) {
     });
 }
 export async function loadLocalSlSourceRecords(project, input) {
-    const connectionId = assertSafeConnectionId(input.connectionId);
+    if (input.connectionId === FEDERATED_CONNECTION_ID) {
+        const descriptor = deriveFederatedConnection(project.config.connections, project.projectDir);
+        if (!descriptor) {
+            return [];
+        }
+        const perMember = await Promise.all(descriptor.members.map(async (member) => {
+            const records = await loadSingleConnectionSourceRecords(project, member.connectionId);
+            return records.map((record) => {
+                // The federated view is one virtual connection: rows carry its id and a
+                // member-prefixed name, so a listing/search row round-trips to
+                // `ktx sl -c _ktx_federated read <name>`. Member origin lives in the name.
+                const name = `${member.connectionId}.${record.name}`;
+                return {
+                    ...record,
+                    connectionId: FEDERATED_CONNECTION_ID,
+                    name,
+                    source: { ...record.source, name },
+                };
+            });
+        }));
+        return perMember.flat();
+    }
+    return loadSingleConnectionSourceRecords(project, input.connectionId);
+}
+async function loadSingleConnectionSourceRecords(project, rawConnectionId) {
+    const connectionId = assertSafeConnectionId(rawConnectionId);
     const dir = `semantic-layer/${connectionId}`;
     const schemaDir = `${dir}/_schema`;
     const listed = await project.fileStore.listFiles(dir);
-    const paths = listed.files.filter((file) => file.endsWith('.yaml') || file.endsWith('.yml')).sort();
+    const paths = listed.files.filter(isSlYamlPath).sort();
     const sources = new Map();
     for (const path of paths.filter((file) => file.startsWith(`${schemaDir}/`))) {
         const raw = await project.fileStore.readFile(path);
-        const tables = manifestTables(parseYamlRecord(raw.content));
+        let tables;
+        try {
+            tables = manifestTables(parseYamlRecord(raw.content));
+        }
+        catch (error) {
+            throw new Error(`${path}: ${error instanceof Error ? error.message : String(error)}`);
+        }
         if (!tables) {
             continue;
         }
@@ -146,7 +142,30 @@ export async function loadLocalSlSourceRecords(project, input) {
     }
     for (const path of paths.filter((file) => !file.startsWith(`${schemaDir}/`))) {
         const raw = await project.fileStore.readFile(path);
-        const parsed = parseYamlRecord(raw.content);
+        let parsed;
+        try {
+            parsed = parseYamlRecord(raw.content);
+        }
+        catch {
+            // A source mid-edit (e.g. an agent saved half-written YAML) must not take
+            // down reads, listings, or search for its siblings. Key it by the same
+            // name the writer side uses (the intact top-level `name:`, recovered even
+            // when the YAML is broken below it; filename only as a last resort) so a
+            // broken uppercase/hashed/human-renamed source stays reachable under its
+            // real name, and surface the raw content for repair.
+            const brokenName = slSourceNameForFile(path, raw.content);
+            sources.set(brokenName, {
+                connectionId,
+                name: brokenName,
+                path,
+                columnCount: 0,
+                measureCount: 0,
+                joinCount: 0,
+                yaml: raw.content,
+                source: { name: brokenName, grain: [], columns: [], joins: [], measures: [] },
+            });
+            continue;
+        }
         const name = typeof parsed.name === 'string' && parsed.name.length > 0 ? parsed.name : sourceNameFromPath(path);
         if (parsed.table || parsed.sql) {
             const source = parsedStandaloneSource(parsed, name);
@@ -191,36 +210,18 @@ export async function validateLocalSlSource(rawYaml, options) {
         return { valid: false, errors: validationErrors(error) };
     }
 }
-/** @internal */
-export async function writeLocalSlSource(project, input) {
-    const validation = await validateLocalSlSource(input.yaml, { project, connectionId: input.connectionId });
-    if (!validation.valid) {
-        throw new Error(`Invalid semantic-layer source: ${validation.errors.join('; ')}`);
-    }
-    const parsed = parseYamlRecord(input.yaml);
-    if (typeof parsed.name === 'string' && parsed.name !== input.sourceName) {
-        throw new Error(`Semantic-layer source name "${parsed.name}" does not match requested path "${input.sourceName}"`);
-    }
-    const path = slPath(input.connectionId, input.sourceName);
-    return project.fileStore.writeFile(path, input.yaml.endsWith('\n') ? input.yaml : `${input.yaml}\n`, LOCAL_AUTHOR, LOCAL_AUTHOR_EMAIL, `Write semantic-layer source: ${input.connectionId}/${input.sourceName}`);
-}
-/** @internal */
 export async function readLocalSlSource(project, input) {
-    const path = slPath(input.connectionId, input.sourceName);
-    try {
-        const result = await project.fileStore.readFile(path);
-        return {
-            ...summarizeSource({ connectionId: input.connectionId, path, raw: result.content }),
-            yaml: result.content,
-        };
-    }
-    catch {
-        const records = await loadLocalSlSourceRecords(project, {
-            connectionId: input.connectionId,
-        });
-        const record = records.find((source) => source.name === input.sourceName);
-        return record ? { ...record } : null;
-    }
+    // Source identity is the in-file `name:` (mirroring the warehouse identifier
+    // verbatim, e.g. Snowflake's uppercase `WIDGET_SALES`), never the filename. The
+    // record loader resolves standalone files, overlays, manifest-backed sources,
+    // and mid-edit files whose YAML no longer parses — so readers — `ktx sl read`,
+    // `ktx sl validate`, and the `sl_read_source` MCP tool — can surface broken
+    // content for repair instead of failing on it.
+    const records = await loadLocalSlSourceRecords(project, {
+        connectionId: input.connectionId,
+    });
+    const record = records.find((source) => source.name === input.sourceName);
+    return record ? { ...record } : null;
 }
 export async function resolveLocalSlSource(project, input) {
     if (input.connectionId !== undefined) {

package/dist/context/sl/semantic-layer.service.d.ts

@@ -38,17 +38,23 @@ export declare class SemanticLayerService {
         name: string;
         connectionType: string;
     }>>;
-    private sourcePath;
+    private resolveWritePath;
     writeSource(connectionId: string, source: SemanticLayerSource, author: string, authorEmail: string, commitMessage?: string, options?: WriteSourceOptions & {
         skipLock?: boolean;
     }): Promise<{
+        path: string;
         warnings: string[];
         commitHash?: string | null;
     }>;
+    /**
+     * Raw standalone/overlay file for a source, resolved by its in-file `name:`.
+     * Returns null when no file declares the name (the source may still exist as
+     * a manifest entry under `_schema/`).
+     */
     readSourceFile(connectionId: string, sourceName: string): Promise<{
         content: string;
         path: string;
-    }>;
+    } | null>;
     loadSource(connectionId: string, sourceName: string): Promise<SemanticLayerSource | null>;
     loadAllSources(connectionId: string): Promise<LoadAllSourcesResult>;
     /**
@@ -87,14 +93,8 @@ export declare class SemanticLayerService {
     } | null>;
     validatePhysicalTableReferences(connectionId: string, sources: SemanticLayerSource[]): Promise<string[]>;
     getDialectForConnection(connectionId: string): Promise<string>;
-    listSourceNames(connectionId: string): Promise<string[]>;
     listFilesForConnection(connectionId: string): Promise<string[]>;
-    readFileByPath(connectionId: string, relativePath: string): Promise<{
-        content: string;
-        readOnly: boolean;
-    }>;
     deleteSource(connectionId: string, sourceName: string, author: string, authorEmail: string): Promise<import("../../context/core/file-store.js").KtxFileWriteResult | null>;
-    getSourceHistory(connectionId: string, sourceName: string): Promise<unknown>;
     /**
      * Validate the semantic layer state that *would* exist if `proposedSource`
      * were written, without persisting anything. Used by write/edit tools to
@@ -203,6 +203,23 @@ export interface ManifestTableEntry {
     usage?: TableUsageOutput;
 }
 export declare function projectManifestEntry(name: string, entry: ManifestTableEntry): SemanticLayerSource;
+export interface MissingJoinTarget {
+    to: string;
+    /** Source whose name matches only case-insensitively, if any — the usual authoring mistake. */
+    caseMismatch: string | null;
+}
+/**
+ * Join targets that do not exactly match a known source name. The Python
+ * engine resolves `joins[].to` by exact name within one connection's source
+ * set (`engine._collect_orphan_join_target_errors`) and `query()` raises on a
+ * miss, so anything looser here — case-insensitive matches, table refs,
+ * sources in other connections — would pass this gate and then fail
+ * query/validation as an orphan join target.
+ */
+export declare function findMissingJoinTargets(joins: Array<{
+    to: string;
+}> | undefined, knownSourceNames: Iterable<string>): MissingJoinTarget[];
+export declare function formatMissingJoinTarget(missing: MissingJoinTarget): string;
 /**
  * Returns one message per measure-level segment reference that doesn't resolve to
  * a segment defined on the source. Array is empty when every reference checks out.

package/dist/context/sl/semantic-layer.service.js

@@ -2,6 +2,7 @@ import YAML from 'yaml';
 import { noopLogger } from '../../context/core/config.js';
 import { normalizeSemanticLayerDescriptions } from './description-normalization.js';
 import { isOverlaySource, resolvedSourceSchema, sourceDefinitionSchema, sourceOverlaySchema } from './schemas.js';
+import { isSlYamlPath, resolveSlSourceFile, slDeclaredSourceName, slSourceFilePath } from './source-files.js';
 const SL_DIR_PREFIX = 'semantic-layer';
 const CONNECTION_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
 /** @internal */
@@ -85,7 +86,7 @@ export class SemanticLayerService {
     async listConnectionIds() {
         try {
             const result = await this.configService.listFiles(SL_DIR_PREFIX);
-            // Directories under semantic-layer/ are connectionIds. Local KTX projects use
+            // Directories under semantic-layer/ are connectionIds. Local ktx projects use
             // readable ids like "warehouse" and "dbt-main", not only UUIDs.
             return result.files
                 .map((f) => f.replace(`${SL_DIR_PREFIX}/`, '').split('/')[0])
@@ -104,8 +105,31 @@ export class SemanticLayerService {
         return this.connections.listEnabledConnections(ids);
     }
     // ── YAML File Operations ────────────────────────────────
-    sourcePath(connectionId, sourceName) {
-        return `${SL_DIR_PREFIX}/${connectionId}/${sourceName}.yaml`;
+    // The in-file `name:` is the source's identity; the filename is only a derived
+    // label. Rewrites land on the file that already declares the name (humans may
+    // rename files freely); new sources get a derived filename. A file already
+    // sitting at the derived path that declares a name declares a *different* one
+    // (the resolver would have matched it otherwise) — fail instead of clobbering
+    // it. A nameless/unparseable file there is the broken remains of this very
+    // source (the derived path is a function of the name), so overwriting it is
+    // the repair path, not data loss.
+    async resolveWritePath(connectionId, sourceName) {
+        const existing = await resolveSlSourceFile(this.configService, connectionId, sourceName);
+        if (existing) {
+            return existing.path;
+        }
+        const path = slSourceFilePath(connectionId, sourceName);
+        let occupant = null;
+        try {
+            occupant = slDeclaredSourceName((await this.configService.readFile(path)).content);
+        }
+        catch {
+            return path;
+        }
+        if (occupant !== null) {
+            throw new Error(`Cannot write source '${sourceName}': ${path} already defines source '${occupant}'`);
+        }
+        return path;
     }
     async writeSource(connectionId, source, author, authorEmail, commitMessage, options) {
         // Writes are intentionally permissive — the agent must be able to save broken files so
@@ -140,38 +164,40 @@ export class SemanticLayerService {
                 this.logger.warn(`[writeSource] '${source.name}': ${danglingRefs.join('; ')}. Saving anyway.`);
             }
         }
-        const path = this.sourcePath(connectionId, source.name);
+        const path = await this.resolveWritePath(connectionId, source.name);
         const normalizedSource = normalizeSemanticLayerDescriptions(source);
         const content = YAML.stringify(normalizedSource, { indent: 2, lineWidth: 0, version: '1.1' });
         const message = commitMessage ?? `Update semantic layer source: ${source.name}`;
         const result = await this.configService.writeFile(path, content, author, authorEmail, message, {
             skipLock: options?.skipLock,
         });
-        return { ...result, warnings };
+        // The filename is derived from (or resolved by) the source name — surface
+        // the actual path so callers don't have to re-resolve it.
+        return { ...result, path, warnings };
     }
+    /**
+     * Raw standalone/overlay file for a source, resolved by its in-file `name:`.
+     * Returns null when no file declares the name (the source may still exist as
+     * a manifest entry under `_schema/`).
+     */
     async readSourceFile(connectionId, sourceName) {
-        const path = this.sourcePath(connectionId, sourceName);
-        const result = await this.configService.readFile(path);
-        return { content: result.content, path };
+        const file = await resolveSlSourceFile(this.configService, connectionId, sourceName);
+        return file ? { content: file.content, path: file.path } : null;
     }
     async loadSource(connectionId, sourceName) {
-        let content;
-        try {
-            const result = await this.readSourceFile(connectionId, sourceName);
-            content = result.content;
-        }
-        catch {
+        const file = await this.readSourceFile(connectionId, sourceName);
+        if (!file) {
             return null;
         }
         try {
-            return YAML.parse(content);
+            return YAML.parse(file.content);
         }
         catch (error) {
             // Distinguish a YAML parse failure from a missing file. The file exists but
             // its contents are unparseable — callers that treat null as "does not exist"
             // could otherwise overwrite the broken file. Surface the parse failure via
             // the service logger so the broken source is at least visible.
-            this.logger.warn(`[loadSource] ${connectionId}/${sourceName}.yaml: YAML parse failed: ${error instanceof Error ? error.message : String(error)}`);
+            this.logger.warn(`[loadSource] ${file.path}: YAML parse failed: ${error instanceof Error ? error.message : String(error)}`);
             return null;
         }
     }
@@ -182,7 +208,7 @@ export class SemanticLayerService {
         let allFiles;
         try {
             const result = await this.configService.listFiles(dir);
-            allFiles = result.files.filter((f) => f.endsWith('.yaml'));
+            allFiles = result.files.filter((f) => isSlYamlPath(f));
         }
         catch (e) {
             const message = `Failed to list semantic-layer files under ${dir}: ${e instanceof Error ? e.message : String(e)}`;
@@ -283,7 +309,7 @@ export class SemanticLayerService {
         let allFiles;
         try {
             const listing = await this.configService.listFiles(dir);
-            allFiles = listing.files.filter((f) => f.endsWith('.yaml'));
+            allFiles = listing.files.filter((f) => isSlYamlPath(f));
         }
         catch {
             return result;
@@ -350,7 +376,7 @@ export class SemanticLayerService {
         const schemaDir = `${SL_DIR_PREFIX}/${connectionId}/_schema`;
         try {
             const result = await this.configService.listFiles(schemaDir);
-            const yamlFiles = result.files.filter((f) => f.endsWith('.yaml'));
+            const yamlFiles = result.files.filter((f) => isSlYamlPath(f));
             for (const filePath of yamlFiles) {
                 try {
                     const { content } = await this.configService.readFile(filePath);
@@ -390,7 +416,7 @@ export class SemanticLayerService {
         let yamlFiles;
         try {
             const result = await this.configService.listFiles(schemaDir);
-            yamlFiles = result.files.filter((f) => f.endsWith('.yaml'));
+            yamlFiles = result.files.filter((f) => isSlYamlPath(f));
         }
         catch {
             return null;
@@ -457,7 +483,7 @@ export class SemanticLayerService {
                 .filter((c) => !c.expr && !manifestColumns.has(c.name.toLowerCase()))
                 .map((c) => c.name);
             if (absentDeclaredColumns.length > 0) {
-                errors.push(`${source.name}.yaml: table "${source.table}" matched manifest ${manifestLabel}, ` +
+                errors.push(`${source.name}: table "${source.table}" matched manifest ${manifestLabel}, ` +
                     `but declared column(s) absent from physical table: ${absentDeclaredColumns.join(', ')}. ` +
                     `Available columns: ${[...manifestColumns.values()].join(', ')}`);
             }
@@ -466,7 +492,7 @@ export class SemanticLayerService {
                 return !declared || (!declared.expr && !manifestColumns.has(grain.toLowerCase()));
             });
             if (missingGrainColumns.length > 0) {
-                errors.push(`${source.name}.yaml: grain column(s) absent from physical table "${source.table}": ${missingGrainColumns.join(', ')}`);
+                errors.push(`${source.name}: grain column(s) absent from physical table "${source.table}": ${missingGrainColumns.join(', ')}`);
             }
             for (const column of declaredColumns) {
                 if (!column.expr) {
@@ -480,7 +506,7 @@ export class SemanticLayerService {
                     validMeasures: new Set(),
                 });
                 if (missing.length > 0) {
-                    errors.push(`${source.name}.yaml: computed column "${column.name}" references unknown column(s): ${missing.join(', ')}`);
+                    errors.push(`${source.name}: computed column "${column.name}" references unknown column(s): ${missing.join(', ')}`);
                 }
             }
             for (const segment of source.segments ?? []) {
@@ -492,7 +518,7 @@ export class SemanticLayerService {
                     validMeasures: new Set(),
                 });
                 if (missing.length > 0) {
-                    errors.push(`${source.name}.yaml: segment "${segment.name}" references unknown column(s): ${missing.join(', ')}`);
+                    errors.push(`${source.name}: segment "${segment.name}" references unknown column(s): ${missing.join(', ')}`);
                 }
             }
             for (const measure of source.measures ?? []) {
@@ -504,7 +530,7 @@ export class SemanticLayerService {
                     validMeasures: measureNames,
                 });
                 if (exprMissing.length > 0) {
-                    errors.push(`${source.name}.yaml: measure "${measure.name}" references unknown column(s): ${exprMissing.join(', ')}`);
+                    errors.push(`${source.name}: measure "${measure.name}" references unknown column(s): ${exprMissing.join(', ')}`);
                 }
                 if (measure.filter) {
                     const filterMissing = missingLocalExpressionRefs({
@@ -515,7 +541,7 @@ export class SemanticLayerService {
                         validMeasures: new Set(),
                     });
                     if (filterMissing.length > 0) {
-                        errors.push(`${source.name}.yaml: measure "${measure.name}" filter references unknown column(s): ${filterMissing.join(', ')}`);
+                        errors.push(`${source.name}: measure "${measure.name}" filter references unknown column(s): ${filterMissing.join(', ')}`);
                     }
                 }
             }
@@ -525,7 +551,7 @@ export class SemanticLayerService {
                     continue;
                 }
                 if (!validOutputColumns.has(parsed.localColumn.toLowerCase())) {
-                    errors.push(`${source.name}.yaml: join to "${join.to}" references local column ` +
+                    errors.push(`${source.name}: join to "${join.to}" references local column ` +
                         `"${parsed.localColumn}" that is not a valid output column`);
                 }
                 const targetSource = sourcesByName.get(join.to.toLowerCase()) ??
@@ -533,7 +559,7 @@ export class SemanticLayerService {
                 if (targetSource) {
                     const targetColumns = new Set(targetSource.columns.map((c) => c.name.toLowerCase()));
                     if (!targetColumns.has(parsed.targetColumn.toLowerCase())) {
-                        errors.push(`${source.name}.yaml: join to "${join.to}" references target column ` +
+                        errors.push(`${source.name}: join to "${join.to}" references target column ` +
                             `"${parsed.targetColumn}" that does not exist on the target source`);
                     }
                 }
@@ -548,41 +574,28 @@ export class SemanticLayerService {
         }
         return SemanticLayerService.mapDialect(connection.connectionType);
     }
-    async listSourceNames(connectionId) {
-        const dir = `${SL_DIR_PREFIX}/${connectionId}`;
-        try {
-            const result = await this.configService.listFiles(dir);
-            return result.files.filter((f) => f.endsWith('.yaml')).map((f) => f.replace(`${dir}/`, '').replace('.yaml', ''));
-        }
-        catch {
-            return [];
-        }
-    }
     async listFilesForConnection(connectionId) {
         const dir = `${SL_DIR_PREFIX}/${connectionId}`;
         try {
             const result = await this.configService.listFiles(dir, true);
-            return result.files.filter((f) => f.endsWith('.yaml'));
+            return result.files.filter((f) => isSlYamlPath(f));
         }
         catch {
             return [];
         }
     }
-    async readFileByPath(connectionId, relativePath) {
-        const fullPath = `${SL_DIR_PREFIX}/${connectionId}/${relativePath}`;
-        const result = await this.configService.readFile(fullPath);
-        return {
-            content: result.content,
-            readOnly: relativePath.startsWith('_schema/'),
-        };
-    }
     async deleteSource(connectionId, sourceName, author, authorEmail) {
-        const path = this.sourcePath(connectionId, sourceName);
-        return this.configService.deleteFile(path, author, authorEmail, `Delete semantic layer source: ${sourceName}`);
-    }
-    async getSourceHistory(connectionId, sourceName) {
-        const path = this.sourcePath(connectionId, sourceName);
-        return this.configService.getFileHistory(path);
+        const file = await resolveSlSourceFile(this.configService, connectionId, sourceName);
+        if (!file) {
+            // `deleteFile` returns null for a missing path, which would let a no-op
+            // delete read as success. Distinguish the two real cases instead.
+            if (await this.isManifestBacked(connectionId, sourceName)) {
+                throw new Error(`Source '${sourceName}' is defined by the scan manifest (_schema/) and has no overlay file to delete. ` +
+                    `Rescan the connection to remove it from the manifest.`);
+            }
+            throw new Error(`Semantic-layer source not found: ${connectionId}/${sourceName}`);
+        }
+        return this.configService.deleteFile(file.path, author, authorEmail, `Delete semantic layer source: ${sourceName}`);
     }
     /**
      * Validate the semantic layer state that *would* exist if `proposedSource`
@@ -639,6 +652,16 @@ export class SemanticLayerService {
             // any column-without-type errors via the warehouse probe.
         }
         merged.push(toPush);
+        // A join target the engine cannot resolve fails every downstream gate and
+        // query with the error attributed to the phantom target. Reject it here,
+        // on the source that declares it, while the writing agent can still fix it.
+        const missingJoinTargets = findMissingJoinTargets(toPush.joins, merged.map((s) => s.name));
+        const joinTargetErrors = missingJoinTargets.map((missing) => `${toPush.name}: ${formatMissingJoinTarget(missing)}. Declare joins only to existing ` +
+            `semantic-layer sources in this connection, or drop the join and keep the relationship ` +
+            `in a column description.`);
+        if (joinTargetErrors.length > 0) {
+            return { errors: [...loadErrors, ...joinTargetErrors], warnings: [], perSourceWarnings: {} };
+        }
         const validatable = merged.filter((s) => s.table != null || s.sql != null);
         if (validatable.length === 0) {
             return { errors: loadErrors, warnings: [], perSourceWarnings: {} };
@@ -704,7 +727,7 @@ export class SemanticLayerService {
         catch {
             return [];
         }
-        const schemaFiles = files.filter((file) => /^semantic-layer\/[^/]+\/_schema\/.+\.ya?ml$/.test(file));
+        const schemaFiles = files.filter((file) => /^semantic-layer\/[^/]+\/_schema\//.test(file) && isSlYamlPath(file));
         const entries = [];
         for (const filePath of schemaFiles) {
             const connectionId = filePath.split('/')[1];
@@ -732,7 +755,7 @@ export class SemanticLayerService {
         let allFiles;
         try {
             const result = await this.configService.listFiles(dir);
-            allFiles = result.files.filter((f) => f.endsWith('.yaml'));
+            allFiles = result.files.filter((f) => isSlYamlPath(f));
         }
         catch {
             return warnings;
@@ -883,7 +906,7 @@ export class SemanticLayerService {
         const tables = new Map();
         try {
             const result = await this.configService.listFiles(dir);
-            const yamlFiles = result.files.filter((f) => f.endsWith('.yaml'));
+            const yamlFiles = result.files.filter((f) => isSlYamlPath(f));
             for (const filePath of yamlFiles) {
                 try {
                     const { content } = await this.configService.readFile(filePath);
@@ -1182,6 +1205,36 @@ function parseJoinColumns(on, sourceName, targetName) {
     }
     return { localColumn: left.column, targetColumn: right.column };
 }
+/**
+ * Join targets that do not exactly match a known source name. The Python
+ * engine resolves `joins[].to` by exact name within one connection's source
+ * set (`engine._collect_orphan_join_target_errors`) and `query()` raises on a
+ * miss, so anything looser here — case-insensitive matches, table refs,
+ * sources in other connections — would pass this gate and then fail
+ * query/validation as an orphan join target.
+ */
+export function findMissingJoinTargets(joins, knownSourceNames) {
+    const known = new Set();
+    const canonicalByLower = new Map();
+    for (const name of knownSourceNames) {
+        known.add(name);
+        canonicalByLower.set(name.toLowerCase(), name);
+    }
+    const missing = [];
+    for (const join of joins ?? []) {
+        if (known.has(join.to)) {
+            continue;
+        }
+        missing.push({ to: join.to, caseMismatch: canonicalByLower.get(join.to.toLowerCase()) ?? null });
+    }
+    return missing;
+}
+export function formatMissingJoinTarget(missing) {
+    const hint = missing.caseMismatch
+        ? `; join targets are case-sensitive — the source is named "${missing.caseMismatch}"`
+        : '';
+    return `join target "${missing.to}" does not exist${hint}`;
+}
 /**
  * Returns one message per measure-level segment reference that doesn't resolve to
  * a segment defined on the source. Array is empty when every reference checks out.

package/dist/context/sl/source-files.d.ts

@@ -0,0 +1,48 @@
+import type { KtxFileStorePort } from '../../context/core/file-store.js';
+/** @internal */
+export declare function isReservedConnectionId(connectionId: string): boolean;
+export declare function assertSafeConnectionId(connectionId: string): string;
+export declare function isSafeConnectionId(connectionId: string | undefined): connectionId is string;
+export declare function sourceNameFromPath(path: string): string;
+export declare function isSlYamlPath(path: string): boolean;
+/**
+ * Derive the filename for a semantic-layer source. Total over all possible
+ * source names — never throws.
+ *
+ * Names that are already safe lowercase snake_case become `<name>.yaml`;
+ * anything else becomes `<slug>-<8 hex of sha256(name)>.yaml`. The two ranges
+ * are disjoint and the mapping is injective: safe filenames contain no `-`,
+ * hashed filenames always end in `-<8 hex>`, and slugs are lowercased so names
+ * differing only by case get distinct hashes instead of colliding paths on
+ * case-insensitive filesystems (macOS APFS, Windows).
+ *
+ * @internal
+ */
+export declare function slSourceFileName(sourceName: string): string;
+export declare function slSourceFilePath(connectionId: string, sourceName: string): string;
+export interface SlSourceFile {
+    path: string;
+    content: string;
+}
+export declare function slSourceNameForFile(path: string, content: string): string;
+/**
+ * The `name:` a semantic-layer YAML file declares, or null when the file is
+ * nameless or so broken even the name is unrecoverable. Null is how
+ * `writeSource` tells a genuine name conflict at a derived path apart from the
+ * broken remains of the source being written, which a rewrite must repair
+ * rather than refuse.
+ *
+ * Uses `parseDocument`, not `parse`: a file with a syntax error below the
+ * `name:` line still parses into a partial tree whose top-level `name:` is
+ * intact. `parse` would throw on the same input and drop the source to its
+ * filename — wrong for human-renamed files, whose filename is not the name.
+ */
+export declare function slDeclaredSourceName(content: string): string | null;
+/**
+ * Find the standalone/overlay file that defines `sourceName` for a connection.
+ * Returns null when no file declares the name (the source may still exist as a
+ * manifest entry under `_schema/`). Throws when more than one file declares the
+ * same name — that breaks the one-file-per-name invariant and must be repaired
+ * by hand rather than silently picking one.
+ */
+export declare function resolveSlSourceFile(fileStore: Pick<KtxFileStorePort, 'listFiles' | 'readFile'>, connectionId: string, sourceName: string): Promise<SlSourceFile | null>;