@kaelio/ktx 0.10.0 → 0.12.0

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,46 @@
+import type { KtxFileStorePort } from '../../context/core/file-store.js';
+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>;

package/dist/context/sl/source-files.js

@@ -0,0 +1,131 @@
+import { createHash } from 'node:crypto';
+import YAML from 'yaml';
+// Semantic-layer source identity lives in the file's `name:` field, which mirrors
+// the warehouse identifier verbatim (Snowflake's uppercase `SIGNED_UP`, `EVENT$LOG`).
+// The filename is a derived label and never participates in identity: reads resolve
+// a source by scanning the connection directory and matching `name:`, and writes
+// reuse the resolved file's path, so files can be freely renamed by humans without
+// changing which source they define.
+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;
+}
+export function assertSafeConnectionId(connectionId) {
+    if (!isSafeConnectionId(connectionId)) {
+        throw new Error(`Unsafe connection id: ${connectionId}`);
+    }
+    return assertSafePathToken('connection id', connectionId);
+}
+export function isSafeConnectionId(connectionId) {
+    return typeof connectionId === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(connectionId);
+}
+export function sourceNameFromPath(path) {
+    return (path
+        .split('/')
+        .at(-1)
+        ?.replace(/\.ya?ml$/, '') ?? path);
+}
+// The one predicate for "this path is a semantic-layer YAML file". ktx itself
+// always writes `.yaml` (see `slSourceFileName`), but humans rename freely and
+// the dbt ecosystem's habit is `.yml`, so every reader must accept both — a
+// listing that recognizes only one extension makes the same file visible to
+// some entry points and invisible to others.
+export function isSlYamlPath(path) {
+    return path.endsWith('.yaml') || path.endsWith('.yml');
+}
+// Windows refuses these basenames regardless of extension — a genuinely universal
+// filesystem invariant, so the static list is acceptable.
+const WINDOWS_RESERVED_BASENAME = /^(?:con|prn|aux|nul|com[0-9]|lpt[0-9])$/;
+const SAFE_FILE_BASENAME = /^[a-z0-9][a-z0-9_]{0,63}$/;
+/**
+ * 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 function slSourceFileName(sourceName) {
+    if (SAFE_FILE_BASENAME.test(sourceName) && !WINDOWS_RESERVED_BASENAME.test(sourceName)) {
+        return `${sourceName}.yaml`;
+    }
+    const slug = sourceName
+        .toLowerCase()
+        .replace(/[^a-z0-9_]+/g, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .slice(0, 64);
+    const hash = createHash('sha256').update(sourceName, 'utf-8').digest('hex').slice(0, 8);
+    return `${slug || 'src'}-${hash}.yaml`;
+}
+export function slSourceFilePath(connectionId, sourceName) {
+    return `semantic-layer/${assertSafeConnectionId(connectionId)}/${slSourceFileName(sourceName)}`;
+}
+// Same keying as `loadLocalSlSourceRecords`: the in-file `name:` is the identity;
+// the filename is only a fallback for files so broken that even the `name:` is
+// unrecoverable, or genuinely nameless ones. A file left mid-edit with a syntax
+// error below its `name:` line keeps its declared identity (see
+// `slDeclaredSourceName`), so a human-renamed source is still addressed by name
+// while broken instead of silently reverting to its filename.
+export function slSourceNameForFile(path, content) {
+    return slDeclaredSourceName(content) ?? sourceNameFromPath(path);
+}
+/**
+ * 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 function slDeclaredSourceName(content) {
+    let doc;
+    try {
+        doc = YAML.parseDocument(content);
+    }
+    catch {
+        return null;
+    }
+    const name = doc.get('name');
+    return typeof name === 'string' && name.length > 0 ? name : 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 async function resolveSlSourceFile(fileStore, connectionId, sourceName) {
+    const dir = `semantic-layer/${assertSafeConnectionId(connectionId)}`;
+    const schemaDir = `${dir}/_schema`;
+    const listed = await fileStore.listFiles(dir);
+    const paths = listed.files.filter((file) => isSlYamlPath(file) && !file.startsWith(`${schemaDir}/`)).sort();
+    const matches = [];
+    for (const path of paths) {
+        const raw = await fileStore.readFile(path);
+        if (slSourceNameForFile(path, raw.content) === sourceName) {
+            matches.push({ path, content: raw.content });
+        }
+    }
+    if (matches.length > 1) {
+        throw new Error(`Multiple semantic-layer files declare source "${sourceName}": ${matches.map((match) => match.path).join(', ')}`);
+    }
+    return matches[0] ?? null;
+}

package/dist/context/sl/tools/base-semantic-layer.tool.d.ts

@@ -1,4 +1,4 @@
-import type { ZodType } from 'zod';
+import type { z } from 'zod';
 import type { GitAuthorResolverPort } from '../../../context/tools/authors.js';
 import type { ToolContext, ToolOutput } from '../../../context/tools/base-tool.js';
 import { BaseTool } from '../../../context/tools/base-tool.js';
@@ -21,7 +21,7 @@ export interface BaseSemanticLayerToolDeps {
     slSearchService: SlSearchService;
     authorResolver: GitAuthorResolverPort;
 }
-export declare abstract class BaseSemanticLayerTool<TInput extends ZodType = ZodType> extends BaseTool<TInput> {
+export declare abstract class BaseSemanticLayerTool<TInput extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> extends BaseTool<TInput> {
     protected readonly semanticLayerService: SemanticLayerService;
     protected readonly slSearchService: SlSearchService;
     protected readonly authorResolver: GitAuthorResolverPort;

package/dist/context/sl/tools/base-semantic-layer.tool.js

@@ -14,13 +14,8 @@ export class BaseSemanticLayerTool extends BaseTool {
     }
     async readSourceYaml(connectionId, sourceName, context) {
         const semanticLayerService = context?.session?.semanticLayerService ?? this.semanticLayerService;
-        try {
-            const { content } = await semanticLayerService.readSourceFile(connectionId, sourceName);
-            return content;
-        }
-        catch {
-            return null;
-        }
+        const file = await semanticLayerService.readSourceFile(connectionId, sourceName);
+        return file?.content ?? null;
     }
     buildMarkdown(success, errors, sourceName, extra) {
         const parts = [];

package/dist/context/sl/tools/sl-edit-source.tool.js

@@ -91,14 +91,8 @@ If no source exists yet, use sl_write_source instead — this tool will reject t
             }
         }
         // Read existing source
-        let currentYaml = null;
-        try {
-            const { content } = await semanticLayerService.readSourceFile(connectionId, sourceName);
-            currentYaml = content;
-        }
-        catch {
-            currentYaml = null;
-        }
+        const currentFile = await semanticLayerService.readSourceFile(connectionId, sourceName);
+        const currentYaml = currentFile?.content ?? null;
         if (!currentYaml) {
             const manifestBacked = await semanticLayerService.isManifestBacked(connectionId, sourceName);
             if (manifestBacked) {
@@ -138,6 +132,14 @@ If no source exists yet, use sl_write_source instead — this tool will reject t
         catch (e) {
             return this.buildOutput(false, [`YAML parse error after edits: ${e}`], sourceName);
         }
+        // The in-file `name:` is the source's identity — an edited name would make
+        // writeSource create a second source instead of updating this one.
+        if (source.name !== sourceName) {
+            return this.buildOutput(false, [
+                `Edits change "name:" from "${sourceName}" to "${source.name ?? '<missing>'}" — renaming is not supported. ` +
+                    `Delete the source and recreate it under the new name.`,
+            ], sourceName);
+        }
         source = normalizeSemanticLayerDescriptions(source, { fillMissing: !!context.session?.ingest });
         // Re-serialize and write
         const updatedYaml = YAML.stringify(source, { indent: 2, lineWidth: 0, version: '1.1' });