@kaelio/ktx 0.4.0 → 0.5.0

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

@@ -0,0 +1,179 @@
+import YAML from 'yaml';
+import { z } from 'zod';
+import { addTouchedSlSource } from '../../../context/tools/touched-sl-sources.js';
+import { validateActionRawPaths } from '../../../context/tools/action-raw-paths.js';
+import { validateActionTargetConnection } from '../../../context/tools/action-target-connection.js';
+import { applySqlEdits } from '../../tools/sql-edit-replacer.js';
+import { normalizeSemanticLayerDescriptions } from '../description-normalization.js';
+import { BaseSemanticLayerTool, } from './base-semantic-layer.tool.js';
+import { slToolConnectionIdSchema } from './connection-id-schema.js';
+const slEditSourceInputSchema = z.object({
+    connectionId: slToolConnectionIdSchema.describe('Data source connection ID'),
+    sourceName: z.string().describe('Name of the source to edit'),
+    yaml_edits: z
+        .array(z.object({
+        oldText: z.string().describe('Exact text to find in the current YAML. Must match exactly (byte-for-byte).'),
+        newText: z.string().describe('Replacement text. Use empty string to delete.'),
+        reason: z.string().optional().describe('Brief reason for this edit.'),
+    }))
+        .optional()
+        .describe('Targeted exact-match search/replace edits on the raw YAML content.'),
+    delete: z.boolean().optional().describe('Set to true to delete this source entirely'),
+    rawPaths: z
+        .array(z.string().min(1))
+        .optional()
+        .describe('In ingest sessions, raw source file paths that directly support this SL action.'),
+});
+function actionTargetConnectionId(runConnectionId, actionConnectionId) {
+    return runConnectionId && runConnectionId !== actionConnectionId ? actionConnectionId : null;
+}
+export class SlEditSourceTool extends BaseSemanticLayerTool {
+    name = 'sl_edit_source';
+    constructor(deps) {
+        super(deps);
+    }
+    get description() {
+        return `<purpose>
+Make targeted edits to an existing semantic layer source using exact-match search/replace on YAML content.
+If no source exists yet, use sl_write_source instead — this tool will reject the call.
+</purpose>
+
+<when_to_use>
+- Adding/removing a measure on an existing source
+- Adding/updating a join relationship
+- Updating column descriptions
+- Removing an obsolete source (set delete: true)
+- Consolidation: delete redundant sources, edit the surviving one
+</when_to_use>
+
+<edit_guidelines>
+- yaml_edits: exact-match search/replace on raw YAML. oldText must match byte-for-byte (no whitespace normalization or fuzzy matching).
+  Include enough surrounding context in oldText for a unique match.
+- Read the source first with sl_read_source to copy the exact text you want to replace.
+- Keep edits scoped to the user's request — don't proactively regenerate all measures.
+</edit_guidelines>`;
+    }
+    get inputSchema() {
+        return slEditSourceInputSchema;
+    }
+    async call(input, context) {
+        const { connectionId, sourceName } = input;
+        const { name: author, email: authorEmail } = await this.authorResolver.resolve(context.userId);
+        const semanticLayerService = context.session?.semanticLayerService ?? this.semanticLayerService;
+        const skipIndex = context.session?.isWorktreeScoped === true;
+        const targetConnectionValidation = validateActionTargetConnection(context.session, connectionId);
+        if (!targetConnectionValidation.ok) {
+            return this.buildOutput(false, [targetConnectionValidation.error], sourceName);
+        }
+        const rawPathValidation = validateActionRawPaths(context.session, input.rawPaths);
+        if (!rawPathValidation.ok) {
+            return this.buildOutput(false, [rawPathValidation.error], sourceName);
+        }
+        // Handle delete
+        if (input.delete) {
+            try {
+                await semanticLayerService.deleteSource(connectionId, sourceName, author, authorEmail);
+                if (context.session) {
+                    addTouchedSlSource(context.session.touchedSlSources, connectionId, sourceName);
+                    context.session.actions.push({
+                        target: 'sl',
+                        type: 'removed',
+                        key: sourceName,
+                        detail: 'Deleted source',
+                        targetConnectionId: actionTargetConnectionId(context.session.connectionId, connectionId),
+                        ...(rawPathValidation.rawPaths ? { rawPaths: rawPathValidation.rawPaths } : {}),
+                    });
+                }
+                return this.buildOutput(true, [], sourceName, { yaml: undefined, commitHash: undefined });
+            }
+            catch (error) {
+                return this.buildOutput(false, [error instanceof Error ? error.message : String(error)], sourceName);
+            }
+        }
+        // Read existing source
+        let currentYaml = null;
+        try {
+            const { content } = await semanticLayerService.readSourceFile(connectionId, sourceName);
+            currentYaml = content;
+        }
+        catch {
+            currentYaml = null;
+        }
+        if (!currentYaml) {
+            const manifestBacked = await semanticLayerService.isManifestBacked(connectionId, sourceName);
+            if (manifestBacked) {
+                return this.buildOutput(false, [
+                    [
+                        `Source "${sourceName}" exists in the schema manifest but has no overlay file yet — sl_edit_source cannot edit it directly.`,
+                        `Bootstrap an overlay with sl_write_source, then re-run sl_edit_source on subsequent changes:`,
+                        `  name: ${sourceName}`,
+                        `  measures:`,
+                        `    - name: <measure_name>`,
+                        `      expr: "<expression>"`,
+                        `      description: "<what it measures>"`,
+                        `Overlay shape: "name:" plus any of "measures:", "segments:", "descriptions:", "joins:", "disable_joins:", "exclude_columns:", "column_overrides:", or computed-only "columns:" entries with expr + type.`,
+                        `Do NOT include "sql:", "table:", "grain:", or base-table "columns:" — those are inherited from the manifest.`,
+                    ].join('\n'),
+                ], sourceName);
+            }
+            return this.buildOutput(false, ['Source not found. Use sl_write_source to create it.'], sourceName);
+        }
+        const errors = [];
+        let yaml = currentYaml;
+        let editCount = 0;
+        // Apply yaml_edits (text-level search/replace, exact-match only)
+        if (input.yaml_edits && input.yaml_edits.length > 0) {
+            const editResult = applySqlEdits(yaml, input.yaml_edits, { exactOnly: true });
+            yaml = editResult.sql;
+            editCount = editResult.appliedEdits;
+            if (!editResult.success) {
+                errors.push(...editResult.errors);
+            }
+        }
+        // Parse resulting YAML
+        let source;
+        try {
+            source = YAML.parse(yaml);
+        }
+        catch (e) {
+            return this.buildOutput(false, [`YAML parse error after edits: ${e}`], sourceName);
+        }
+        source = normalizeSemanticLayerDescriptions(source, { fillMissing: !!context.session?.ingest });
+        // Re-serialize and write
+        const updatedYaml = YAML.stringify(source, { indent: 2, lineWidth: 0, version: '1.1' });
+        const { errors: validationErrors, warnings: validationWarnings } = await semanticLayerService.validateWithProposedSource(connectionId, source);
+        if (validationErrors.length > 0) {
+            return this.buildOutput(false, [...errors, 'Validation failed — edits were NOT saved:', ...validationErrors], sourceName, { yaml: updatedYaml, editCount, validationErrors, validationWarnings });
+        }
+        const commitMessage = `Edit source ${sourceName}: ${input.yaml_edits ? `${input.yaml_edits.length} YAML edit(s)` : 'update'}`;
+        try {
+            const result = await semanticLayerService.writeSource(connectionId, source, author, authorEmail, commitMessage);
+            if (!skipIndex) {
+                const { sources: allSources } = await semanticLayerService.loadAllSources(connectionId);
+                await this.slSearchService.indexSources(connectionId, allSources).catch(() => { });
+            }
+            if (context.session) {
+                addTouchedSlSource(context.session.touchedSlSources, connectionId, sourceName);
+                context.session.actions.push({
+                    target: 'sl',
+                    type: 'updated',
+                    key: sourceName,
+                    detail: `Applied ${editCount} edit(s)`,
+                    targetConnectionId: actionTargetConnectionId(context.session.connectionId, connectionId),
+                    ...(rawPathValidation.rawPaths ? { rawPaths: rawPathValidation.rawPaths } : {}),
+                });
+            }
+            return this.buildOutput(errors.length === 0, errors, sourceName, {
+                yaml: updatedYaml,
+                commitHash: result.commitHash ?? undefined,
+                editCount,
+                validationErrors,
+                validationWarnings,
+            });
+        }
+        catch (error) {
+            errors.push(error instanceof Error ? error.message : String(error));
+            return this.buildOutput(false, errors, sourceName, { yaml: updatedYaml, editCount });
+        }
+    }
+}

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

@@ -0,0 +1,184 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createTouchedSlSources, hasTouchedSlSource } from '../../../context/tools/touched-sl-sources.js';
+import { SlEditSourceTool } from './sl-edit-source.tool.js';
+function makeTool(overrides = {}) {
+    const semanticLayerService = {
+        readSourceFile: vi.fn().mockResolvedValue({
+            content: 'name: orders\ntable: public.orders\ngrain: [id]\ncolumns:\n  - name: id\n    type: string\nmeasures: []\njoins: []\n',
+        }),
+        validateWithProposedSource: vi.fn().mockResolvedValue({ errors: [], warnings: [] }),
+        writeSource: vi.fn().mockResolvedValue({ commitHash: 'c1' }),
+        loadAllSources: vi.fn().mockResolvedValue({ sources: [], loadErrors: [] }),
+        deleteSource: vi.fn().mockResolvedValue(undefined),
+        isManifestBacked: vi.fn().mockResolvedValue(false),
+        ...overrides.semanticLayerService,
+    };
+    const slSearchService = {
+        indexSources: vi.fn().mockResolvedValue(undefined),
+        ...overrides.slSearchService,
+    };
+    const tool = new SlEditSourceTool({
+        semanticLayerService: semanticLayerService,
+        slSearchService: slSearchService,
+        authorResolver: { resolve: vi.fn().mockResolvedValue({ name: 'T U', email: 't@u.com' }) },
+    });
+    return { tool, semanticLayerService, slSearchService };
+}
+const baseContext = { sourceId: 's', messageId: 'm', userId: 'u' };
+function makeSession(overrides = {}) {
+    return {
+        connectionId: '11111111-1111-1111-1111-111111111111',
+        isWorktreeScoped: true,
+        preHead: 'base',
+        touchedSlSources: createTouchedSlSources(),
+        actions: [],
+        semanticLayerService: {
+            readSourceFile: vi.fn().mockResolvedValue({
+                content: 'name: orders\ntable: public.orders\ngrain: [id]\ncolumns:\n  - name: id\n    type: string\nmeasures: []\njoins: []\n',
+            }),
+            validateWithProposedSource: vi.fn().mockResolvedValue({ errors: [], warnings: [] }),
+            writeSource: vi.fn().mockResolvedValue({ commitHash: 'c1' }),
+            loadAllSources: vi.fn().mockResolvedValue({ sources: [], loadErrors: [] }),
+        },
+        wikiService: {},
+        configService: {},
+        gitService: {},
+        ...overrides,
+    };
+}
+describe('SlEditSourceTool — session gating', () => {
+    it('skips slSearchService.indexSources when session is worktree-scoped', async () => {
+        const { tool, slSearchService } = makeTool();
+        const session = makeSession();
+        const context = { ...baseContext, session };
+        const result = await tool.call({
+            connectionId: session.connectionId,
+            sourceName: 'orders',
+            yaml_edits: [{ oldText: 'measures: []', newText: 'measures: []' }],
+        }, context);
+        expect(result.structured.success).toBe(true);
+        expect(slSearchService.indexSources).not.toHaveBeenCalled();
+        expect(hasTouchedSlSource(session.touchedSlSources, session.connectionId, 'orders')).toBe(true);
+        expect(session.actions).toContainEqual(expect.objectContaining({ target: 'sl', key: 'orders' }));
+    });
+    it('records cross-connection SL edits with targetConnectionId', async () => {
+        const { tool } = makeTool();
+        const session = makeSession({ connectionId: '11111111-1111-4111-8111-111111111111' });
+        const warehouseConnectionId = '22222222-2222-4222-8222-222222222222';
+        const context = { ...baseContext, session };
+        const result = await tool.call({
+            connectionId: warehouseConnectionId,
+            sourceName: 'orders',
+            yaml_edits: [{ oldText: 'measures: []', newText: 'measures: []' }],
+        }, context);
+        expect(result.structured.success).toBe(true);
+        expect(hasTouchedSlSource(session.touchedSlSources, warehouseConnectionId, 'orders')).toBe(true);
+        expect(session.actions).toContainEqual(expect.objectContaining({
+            target: 'sl',
+            type: 'updated',
+            key: 'orders',
+            targetConnectionId: warehouseConnectionId,
+        }));
+    });
+    it('rejects session-scoped edits outside allowed target connections', async () => {
+        const { tool } = makeTool();
+        const session = makeSession({
+            allowedConnectionNames: new Set(['warehouse']),
+        });
+        const context = { ...baseContext, session };
+        const result = await tool.call({
+            connectionId: 'finance',
+            sourceName: 'orders',
+            yaml_edits: [{ oldText: 'measures: []', newText: 'measures: []' }],
+        }, context);
+        expect(result.structured.success).toBe(false);
+        expect(result.markdown).toContain('connectionId "finance" is outside this ingest session');
+        expect(session.actions).toEqual([]);
+    });
+    it('indexes normally when no session is present', async () => {
+        const { tool, slSearchService } = makeTool();
+        const result = await tool.call({
+            connectionId: '11111111-1111-1111-1111-111111111111',
+            sourceName: 'orders',
+            yaml_edits: [{ oldText: 'measures: []', newText: 'measures: []' }],
+        }, baseContext);
+        expect(result.structured.success).toBe(true);
+        expect(slSearchService.indexSources).toHaveBeenCalledTimes(1);
+    });
+    it('uses session.semanticLayerService when session is present', async () => {
+        const { tool } = makeTool();
+        const session = makeSession();
+        const context = { ...baseContext, session };
+        await tool.call({
+            connectionId: session.connectionId,
+            sourceName: 'orders',
+            yaml_edits: [{ oldText: 'measures: []', newText: 'measures: []' }],
+        }, context);
+        expect(session.semanticLayerService.writeSource).toHaveBeenCalled();
+    });
+    it('fills missing descriptions when an ingest session edits a source', async () => {
+        const { tool } = makeTool();
+        const session = makeSession({
+            ingest: { runId: 'run-1', jobId: 'job-1', syncId: 'sync-1', sourceKey: 'dbt' },
+        });
+        const context = { ...baseContext, session };
+        const result = await tool.call({
+            connectionId: session.connectionId,
+            sourceName: 'orders',
+            yaml_edits: [{ oldText: 'measures: []', newText: 'measures: []' }],
+        }, context);
+        expect(result.structured.success).toBe(true);
+        expect(session.semanticLayerService.writeSource).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
+            descriptions: { ktx: expect.stringContaining('orders') },
+            columns: [
+                expect.objectContaining({
+                    descriptions: { ktx: expect.stringContaining('Identifier') },
+                }),
+            ],
+        }), expect.any(String), expect.any(String), expect.any(String));
+    });
+});
+describe('SlEditSourceTool — manifest-backed source without overlay', () => {
+    it('returns a directed hint pointing at sl_write_source + overlay shape', async () => {
+        const { tool, semanticLayerService } = makeTool({
+            semanticLayerService: {
+                readSourceFile: vi.fn().mockRejectedValue(new Error('ENOENT')),
+                isManifestBacked: vi.fn().mockResolvedValue(true),
+            },
+        });
+        const result = await tool.call({
+            connectionId: '11111111-1111-1111-1111-111111111111',
+            sourceName: 'CONSIGNMENTS',
+            yaml_edits: [{ oldText: 'measures: []', newText: 'measures:\n  - name: aav_count\n    expr: count(*)' }],
+        }, baseContext);
+        expect(result.structured.success).toBe(false);
+        expect(semanticLayerService.isManifestBacked).toHaveBeenCalledWith('11111111-1111-1111-1111-111111111111', 'CONSIGNMENTS');
+        expect(semanticLayerService.writeSource).not.toHaveBeenCalled();
+        const joinedErrors = (result.structured.errors ?? []).join('\n');
+        expect(joinedErrors).toContain('CONSIGNMENTS');
+        expect(joinedErrors).toContain('manifest');
+        expect(joinedErrors).toContain('sl_write_source');
+        expect(joinedErrors).toContain('overlay');
+        // Overlay shape: name plus overlay-only fields.
+        expect(joinedErrors).toContain('measures');
+        expect(joinedErrors).toContain('segments');
+        expect(joinedErrors).toContain('column_overrides');
+    });
+    it('still returns the plain "Source not found" error for truly-missing names', async () => {
+        const { tool, semanticLayerService } = makeTool({
+            semanticLayerService: {
+                readSourceFile: vi.fn().mockRejectedValue(new Error('ENOENT')),
+                isManifestBacked: vi.fn().mockResolvedValue(false),
+            },
+        });
+        const result = await tool.call({
+            connectionId: '11111111-1111-1111-1111-111111111111',
+            sourceName: 'does_not_exist',
+            yaml_edits: [{ oldText: 'x', newText: 'y' }],
+        }, baseContext);
+        expect(result.structured.success).toBe(false);
+        expect(result.structured.errors).toEqual(['Source not found. Use sl_write_source to create it.']);
+        expect(semanticLayerService.isManifestBacked).toHaveBeenCalledTimes(1);
+        expect(semanticLayerService.writeSource).not.toHaveBeenCalled();
+    });
+});

package/dist/context/sl/tools/sl-read-source.tool.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import type { ToolContext, ToolOutput } from '../../../context/tools/base-tool.js';
+import { BaseSemanticLayerTool, type BaseSemanticLayerToolDeps } from './base-semantic-layer.tool.js';
+declare const slReadSourceInputSchema: z.ZodObject<{
+    connectionId: z.ZodString;
+    sourceName: z.ZodString;
+}, z.core.$strip>;
+type SlReadSourceInput = z.infer<typeof slReadSourceInputSchema>;
+interface SlReadSourceStructured {
+    sourceName: string;
+    yaml: string;
+}
+export declare class SlReadSourceTool extends BaseSemanticLayerTool<typeof slReadSourceInputSchema> {
+    readonly name = "sl_read_source";
+    constructor(deps: BaseSemanticLayerToolDeps);
+    get description(): string;
+    get inputSchema(): z.ZodObject<{
+        connectionId: z.ZodString;
+        sourceName: z.ZodString;
+    }, z.core.$strip>;
+    call(input: SlReadSourceInput, context: ToolContext): Promise<ToolOutput<SlReadSourceStructured>>;
+}
+export {};

package/dist/context/sl/tools/sl-read-source.tool.session.test.js

@@ -0,0 +1,55 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createTouchedSlSources } from '../../../context/tools/touched-sl-sources.js';
+import { SlReadSourceTool } from './sl-read-source.tool.js';
+function makeTool(overrides = {}) {
+    const semanticLayerService = {
+        readSourceFile: vi.fn().mockResolvedValue({ content: 'name: foo_default\n', path: 'default' }),
+        ...overrides.semanticLayerService,
+    };
+    const tool = new SlReadSourceTool({
+        semanticLayerService: semanticLayerService,
+        slSearchService: {},
+        authorResolver: { resolve: vi.fn() },
+    });
+    return { tool, semanticLayerService };
+}
+function makeContext(overrides = {}) {
+    return {
+        sourceId: 'src',
+        messageId: 'msg',
+        userId: 'user',
+        ...overrides,
+    };
+}
+function makeSession(overrides = {}) {
+    return {
+        connectionId: '11111111-1111-1111-1111-111111111111',
+        isWorktreeScoped: true,
+        preHead: 'base',
+        touchedSlSources: createTouchedSlSources(),
+        actions: [],
+        semanticLayerService: {
+            readSourceFile: vi.fn().mockResolvedValue({ content: 'name: foo_session\n', path: 'session' }),
+        },
+        wikiService: {},
+        configService: {},
+        gitService: {},
+        ...overrides,
+    };
+}
+describe('SlReadSourceTool - session-scoped reads', () => {
+    it('reads through context.session.semanticLayerService when a session is present', async () => {
+        const { tool, semanticLayerService } = makeTool();
+        const session = makeSession();
+        const result = await tool.call({ connectionId: '11111111-1111-1111-1111-111111111111', sourceName: 'foo' }, makeContext({ session }));
+        expect(session.semanticLayerService.readSourceFile).toHaveBeenCalledWith('11111111-1111-1111-1111-111111111111', 'foo');
+        expect(semanticLayerService.readSourceFile).not.toHaveBeenCalled();
+        expect(result.structured.yaml).toContain('foo_session');
+    });
+    it('reads through the default service when no session is present', async () => {
+        const { tool, semanticLayerService } = makeTool();
+        const result = await tool.call({ connectionId: '11111111-1111-1111-1111-111111111111', sourceName: 'foo' }, makeContext());
+        expect(semanticLayerService.readSourceFile).toHaveBeenCalledWith('11111111-1111-1111-1111-111111111111', 'foo');
+        expect(result.structured.yaml).toContain('foo_default');
+    });
+});

package/dist/context/sl/tools/sl-rollback.tool.d.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import { BaseTool, type ToolContext, type ToolOutput } from '../../../context/tools/base-tool.js';
+import type { SlConnectionCatalogPort, SlSourcesIndexPort } from '../ports.js';
+declare const slRollbackInputSchema: z.ZodObject<{
+    sourceName: z.ZodString;
+}, z.core.$strip>;
+type SlRollbackInput = z.infer<typeof slRollbackInputSchema>;
+interface SlRollbackStructured {
+    success: boolean;
+    sourceName: string;
+    outcome?: string;
+}
+export declare class SlRollbackTool extends BaseTool<typeof slRollbackInputSchema> {
+    private readonly slSourcesRepository;
+    private readonly connections;
+    private readonly probeRowCount;
+    readonly name = "sl_rollback";
+    constructor(slSourcesRepository: SlSourcesIndexPort, connections: SlConnectionCatalogPort, probeRowCount: number);
+    get description(): string;
+    get inputSchema(): z.ZodObject<{
+        sourceName: z.ZodString;
+    }, z.core.$strip>;
+    call(input: SlRollbackInput, context: ToolContext): Promise<ToolOutput<SlRollbackStructured>>;
+}
+export {};

package/dist/context/sl/tools/sl-rollback.tool.js

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import { BaseTool } from '../../../context/tools/base-tool.js';
+import { deleteTouchedSlSource } from '../../../context/tools/touched-sl-sources.js';
+import { revertSourceToPreHead } from './sl-warehouse-validation.js';
+const slRollbackInputSchema = z.object({
+    sourceName: z.string().describe('Name of the source to roll back'),
+});
+export class SlRollbackTool extends BaseTool {
+    slSourcesRepository;
+    connections;
+    probeRowCount;
+    name = 'sl_rollback';
+    constructor(slSourcesRepository, connections, probeRowCount) {
+        super();
+        this.slSourcesRepository = slSourcesRepository;
+        this.connections = connections;
+        this.probeRowCount = probeRowCount;
+    }
+    get description() {
+        return `<purpose>
+Abandon this-session changes to a source and restore it to its pre-session state.
+Use when a write/edit failed validation in a way you cannot fix in-session (e.g. the source requires elevated warehouse permissions).
+</purpose>`;
+    }
+    get inputSchema() {
+        return slRollbackInputSchema;
+    }
+    async call(input, context) {
+        const session = context.session;
+        if (!session) {
+            return {
+                markdown: 'Error: sl_rollback requires an active session (ingest WU or memory-agent). Use git revert for interactive rollback.',
+                structured: { success: false, sourceName: input.sourceName },
+            };
+        }
+        if (!session.connectionId) {
+            return {
+                markdown: 'Error: sl_rollback requires a connection-scoped session; this session has no warehouse connection.',
+                structured: { success: false, sourceName: input.sourceName },
+            };
+        }
+        const outcome = await revertSourceToPreHead({
+            semanticLayerService: session.semanticLayerService,
+            connections: this.connections,
+            configService: session.configService,
+            gitService: session.gitService,
+            slSourcesRepository: this.slSourcesRepository,
+            probeRowCount: this.probeRowCount,
+        }, session.connectionId, session.preHead, input.sourceName);
+        deleteTouchedSlSource(session.touchedSlSources, session.connectionId, input.sourceName);
+        for (let i = session.actions.length - 1; i >= 0; i--) {
+            const a = session.actions[i];
+            if (a.target === 'sl' &&
+                a.key === input.sourceName &&
+                (a.targetConnectionId ?? session.connectionId) === session.connectionId) {
+                session.actions.splice(i, 1);
+            }
+        }
+        return {
+            markdown: `Source "${input.sourceName}" rolled back: ${outcome}.`,
+            structured: { success: true, sourceName: input.sourceName, outcome },
+        };
+    }
+}

package/dist/context/sl/tools/sl-rollback.tool.test.js

@@ -0,0 +1,57 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createTouchedSlSources, hasTouchedSlSource } from '../../../context/tools/touched-sl-sources.js';
+import { SlRollbackTool } from './sl-rollback.tool.js';
+function makeSession(overrides = {}) {
+    return {
+        connectionId: 'conn-1',
+        isWorktreeScoped: true,
+        preHead: 'base',
+        touchedSlSources: createTouchedSlSources([{ connectionId: 'conn-1', sourceName: 'orders' }]),
+        actions: [{ target: 'sl', type: 'updated', key: 'orders', detail: 'x' }],
+        semanticLayerService: {},
+        wikiService: {},
+        configService: {
+            writeFile: vi.fn().mockResolvedValue(undefined),
+            deleteFile: vi.fn().mockResolvedValue(undefined),
+        },
+        gitService: { getFileAtCommit: vi.fn().mockResolvedValue('pre: content') },
+        ...overrides,
+    };
+}
+describe('SlRollbackTool', () => {
+    const connections = {
+        getConnectionById: vi.fn(),
+        listEnabledConnections: vi.fn(),
+        executeQuery: vi.fn(),
+    };
+    it('errors when context.session is absent', async () => {
+        const tool = new SlRollbackTool({}, connections, 1);
+        const context = { sourceId: 's', messageId: 'm', userId: 'u' };
+        const result = await tool.call({ sourceName: 'orders' }, context);
+        expect(result.structured.success).toBe(false);
+        expect(result.markdown).toMatch(/session/i);
+    });
+    it('errors when session has no connectionId (wiki-only turn)', async () => {
+        const tool = new SlRollbackTool({}, connections, 1);
+        const session = makeSession({ connectionId: null });
+        const context = { sourceId: 's', messageId: 'm', userId: 'u', session };
+        const result = await tool.call({ sourceName: 'orders' }, context);
+        expect(result.structured.success).toBe(false);
+        expect(result.markdown).toMatch(/connection-scoped session/i);
+        // Session state untouched
+        expect(hasTouchedSlSource(session.touchedSlSources, 'conn-1', 'orders')).toBe(true);
+        expect(session.gitService.getFileAtCommit).not.toHaveBeenCalled();
+    });
+    it('restores the source content from preHead, clears touched set, prunes actions', async () => {
+        const slSourcesRepository = { deleteByConnectionAndName: vi.fn().mockResolvedValue(undefined) };
+        const tool = new SlRollbackTool(slSourcesRepository, connections, 1);
+        const session = makeSession();
+        const context = { sourceId: 's', messageId: 'm', userId: 'u', session };
+        const result = await tool.call({ sourceName: 'orders' }, context);
+        expect(result.structured.success).toBe(true);
+        expect(session.gitService.getFileAtCommit).toHaveBeenCalledWith(expect.stringContaining('orders.yaml'), 'base');
+        expect(session.configService.writeFile).toHaveBeenCalled();
+        expect(hasTouchedSlSource(session.touchedSlSources, 'conn-1', 'orders')).toBe(false);
+        expect(session.actions).toEqual([]);
+    });
+});

package/dist/context/sl/tools/sl-validate.tool.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import type { ToolContext, ToolOutput } from '../../../context/tools/base-tool.js';
+import { SemanticLayerService } from '../semantic-layer.service.js';
+import { BaseSemanticLayerTool, type BaseSemanticLayerToolDeps, type SemanticLayerStructured } from './base-semantic-layer.tool.js';
+declare const slValidateInputSchema: z.ZodObject<{
+    connectionId: z.ZodString;
+}, z.core.$strip>;
+type SlValidateInput = z.infer<typeof slValidateInputSchema>;
+type ValidationReport = {
+    errors: string[];
+    warnings: string[];
+};
+/** @internal */
+export declare function validateSemanticLayerEndpoint(connectionId: string, semanticLayerService: SemanticLayerService): Promise<ValidationReport>;
+export declare class SlValidateTool extends BaseSemanticLayerTool<typeof slValidateInputSchema> {
+    readonly name = "sl_validate";
+    constructor(deps: BaseSemanticLayerToolDeps);
+    get description(): string;
+    get inputSchema(): z.ZodObject<{
+        connectionId: z.ZodString;
+    }, z.core.$strip>;
+    call(input: SlValidateInput, context: ToolContext): Promise<ToolOutput<SemanticLayerStructured>>;
+}
+export {};