@kaelio/ktx 0.4.1 → 0.5.0

package/dist/context/memory/memory-agent.service.test.js

@@ -0,0 +1,413 @@
+import { describe, expect, it, vi } from 'vitest';
+import { validateSingleSource } from '../../context/sl/tools/sl-warehouse-validation.js';
+import { createTouchedSlSources, hasTouchedSlSource } from '../../context/tools/touched-sl-sources.js';
+import { detectCaptureSignals, isWorthAnalyzing } from './capture-signals.js';
+import { MemoryAgentService } from './memory-agent.service.js';
+const passthroughValidator = {
+    validateSingleSource: (d, c, n) => validateSingleSource(d, c, n),
+};
+describe('MemoryAgentService.detectCaptureSignals', () => {
+    it('fires sl on a long user message + SQL aggregate in assistant message', () => {
+        const userMessage = `${'A'.repeat(120)} show me revenue by month`;
+        const result = detectCaptureSignals({
+            userId: 'u',
+            chatId: 'c',
+            userMessage,
+            assistantMessage: 'SELECT SUM(amount) FROM orders GROUP BY month',
+        });
+        expect(result.sl).toBe(true);
+        expect(result.reasons).toContain('sql aggregate in assistant message');
+    });
+    it('does NOT fire sl from aggregate alone when user message is short', () => {
+        const result = detectCaptureSignals({
+            userId: 'u',
+            chatId: 'c',
+            userMessage: 'show revenue',
+            assistantMessage: 'SELECT SUM(amount) FROM orders',
+        });
+        expect(result.sl).toBe(false);
+    });
+    it('fires sl on definition keywords in user message regardless of length', () => {
+        const result = detectCaptureSignals({
+            userId: 'u',
+            chatId: 'c',
+            userMessage: 'going forward exclude cancelled orders from revenue',
+        });
+        expect(result.sl).toBe(true);
+        expect(result.reasons).toContain('sl-style definition keyword in user message');
+    });
+    it('fires knowledge on a definition keyword in user message', () => {
+        const result = detectCaptureSignals({
+            userId: 'u',
+            chatId: 'c',
+            userMessage: 'BYOL stands for Bring Your Own Lab',
+        });
+        expect(result.knowledge).toBe(true);
+        expect(result.reasons).toContain('definition keyword in user message');
+    });
+    it('fires both sl and knowledge when both signals hit', () => {
+        const result = detectCaptureSignals({
+            userId: 'u',
+            chatId: 'c',
+            userMessage: 'going forward, define revenue as sum of paid orders',
+        });
+        expect(result.sl).toBe(true);
+        expect(result.knowledge).toBe(true);
+    });
+    it('fires neither for a plain ad-hoc question', () => {
+        const result = detectCaptureSignals({
+            userId: 'u',
+            chatId: 'c',
+            userMessage: 'how many users signed up last week?',
+            assistantMessage: '12 users.',
+        });
+        expect(result.sl).toBe(false);
+        expect(result.knowledge).toBe(false);
+        expect(result.reasons).toEqual([]);
+    });
+    it('fires knowledge when assistant emits a markdown definition table', () => {
+        const result = detectCaptureSignals({
+            userId: 'u',
+            chatId: 'c',
+            userMessage: 'list our protocols',
+            assistantMessage: '| Term | Definition |\n|---|---|\n| TRT | Testosterone Replacement Therapy |',
+        });
+        expect(result.knowledge).toBe(true);
+        expect(result.reasons).toContain('definition table in assistant message');
+    });
+    it('accepts JOIN and CTE-style aggregates as sl signals', () => {
+        const userMessage = 'B'.repeat(150);
+        const result = detectCaptureSignals({
+            userId: 'u',
+            chatId: 'c',
+            userMessage,
+            assistantMessage: 'WITH base AS (SELECT * FROM x) SELECT * FROM base',
+        });
+        expect(result.sl).toBe(true);
+    });
+    it('reasons array is empty when no signal fires', () => {
+        const result = detectCaptureSignals({
+            userId: 'u',
+            chatId: 'c',
+            userMessage: 'hello',
+        });
+        expect(result.reasons).toEqual([]);
+    });
+    it('detects LookML dialect from view/measure structural keywords', () => {
+        const result = detectCaptureSignals({
+            userId: 'u',
+            chatId: 'c',
+            userMessage: 'ingest this',
+            assistantMessage: 'view: fct_labs {\n  sql_table_name: analytics.fct_labs ;;\n  measure: count_lab_orders { type: count }\n}',
+        });
+        expect(result.dialect).toBe('lookml');
+        expect(result.sl).toBe(true);
+        expect(result.reasons).toContain('lookml structure in assistant message');
+    });
+});
+describe('MemoryAgentService.isWorthAnalyzing (C1 + F1)', () => {
+    const baseInput = (assistantMessage) => ({
+        userId: 'u',
+        chatId: 'c',
+        userMessage: 'Ingest the following content into memory.',
+        assistantMessage,
+    });
+    it('skips a pure LookML wrapper (only view + sql_table_name + dimensions + measure: count)', () => {
+        const wrapper = `view: timeline {
+  sql_table_name: analytics.timeline ;;
+  dimension_group: date { type: time; description: "m/d/Y" }
+  dimension: notes { type: string; description: "notes" }
+  measure: count { type: count }
+}`;
+        expect(isWorthAnalyzing(baseInput(wrapper))).toBe(false);
+    });
+    it('keeps a LookML view with a non-count aggregate (count_distinct, sum, avg, …)', () => {
+        const real = `view: fct_labs {
+  sql_table_name: analytics.fct_labs ;;
+  measure: count_lab_orders { type: count }
+  measure: count_distinct_patients { type: count_distinct; sql: \${admin_user_id} ;; }
+}`;
+        expect(isWorthAnalyzing(baseInput(real))).toBe(true);
+    });
+    it('keeps a LookML view with derived_table even if it has no non-count measures', () => {
+        const derived = `view: lab_results {
+  derived_table: { sql: SELECT * FROM analytics.raw WHERE status = 'final' ;; }
+  dimension: lab_order_id { primary_key: yes; type: string }
+  measure: count { type: count }
+}`;
+        expect(isWorthAnalyzing(baseInput(derived))).toBe(true);
+    });
+    it('keeps a LookML view with sql_always_where', () => {
+        const enforced = `view: rpt_daily_braze_email {
+  sql_table_name: analytics.fct_email_sends ;;
+  sql_always_where: \${TABLE}.channel = 'braze' ;;
+  measure: count { type: count }
+}`;
+        expect(isWorthAnalyzing(baseInput(enforced))).toBe(true);
+    });
+    it('keeps a LookML view with a join: block', () => {
+        const joined = `view: fct_labs {
+  sql_table_name: analytics.fct_labs ;;
+  join: dim_customers {
+    sql_on: \${fct_labs.admin_user_id} = \${dim_customers.admin_user_id} ;;
+    relationship: many_to_one
+  }
+}`;
+        expect(isWorthAnalyzing(baseInput(joined))).toBe(true);
+    });
+});
+describe('MemoryAgentService.reconcileCrossRefs', () => {
+    const buildService = (overrides) => {
+        const wikiService = {
+            readPage: overrides.readPage ?? vi.fn(),
+        };
+        const knowledgeSlRefsRepository = {
+            syncFromWiki: overrides.syncFromWiki ?? vi.fn().mockResolvedValue({ inserted: 0, deleted: 0 }),
+        };
+        const svc = new MemoryAgentService({
+            settings: {
+                knowledge: { userScopedKnowledgeEnabled: false },
+                slValidation: { probeRowCount: 1 },
+                llm: { memoryIngestionModel: 'test-model' },
+            },
+            promptService: undefined,
+            skillsRegistry: undefined,
+            wikiService: wikiService,
+            knowledgeIndex: undefined,
+            knowledgeSlRefs: knowledgeSlRefsRepository,
+            semanticLayerService: undefined,
+            slSearchService: undefined,
+            connections: undefined,
+            rootFileStore: undefined,
+            gitService: undefined,
+            lockingService: undefined,
+            slSourcesRepository: undefined,
+            sessionWorktreeService: undefined,
+            semanticLayerSourceReconciler: undefined,
+            agentRunner: undefined,
+            slValidator: undefined,
+            toolsetFactory: undefined,
+        });
+        return { svc, wikiService, knowledgeSlRefsRepository };
+    };
+    const session = {
+        userId: 'u',
+        chatId: 'c',
+        userMessage: 'test',
+        connectionId: 'conn-1',
+        userScopedEnabled: false,
+        forceGlobalScope: false,
+        touchedSlSources: createTouchedSlSources(),
+        preHead: null,
+    };
+    it('projects a wiki page.sl_refs into knowledge_sl_refs via syncFromWiki', async () => {
+        const { svc, knowledgeSlRefsRepository } = buildService({
+            readPage: vi.fn().mockResolvedValue({
+                pageKey: 'byol-definition',
+                frontmatter: { summary: 'byol', sl_refs: ['fct_labs', 'lab_results'] },
+                content: 'body',
+            }),
+            syncFromWiki: vi.fn().mockResolvedValue({ inserted: 2, deleted: 0 }),
+        });
+        const actions = [{ target: 'wiki', type: 'created', key: 'byol-definition', detail: '' }];
+        const synced = await svc.reconcileCrossRefs(actions, session);
+        expect(synced).toBe(2);
+        expect(knowledgeSlRefsRepository.syncFromWiki).toHaveBeenCalledWith({
+            wikiPageKey: 'byol-definition',
+            wikiScope: 'GLOBAL',
+            wikiScopeId: null,
+            refs: [
+                { connectionId: 'conn-1', sourceName: 'fct_labs' },
+                { connectionId: 'conn-1', sourceName: 'lab_results' },
+            ],
+        });
+    });
+    it('skips sync when the action has no connectionId in session', async () => {
+        const { svc, knowledgeSlRefsRepository } = buildService({
+            readPage: vi.fn().mockResolvedValue({
+                pageKey: 'byol-definition',
+                frontmatter: { summary: 'byol', sl_refs: ['fct_labs'] },
+                content: 'body',
+            }),
+        });
+        const actions = [{ target: 'wiki', type: 'created', key: 'byol-definition', detail: '' }];
+        const synced = await svc.reconcileCrossRefs(actions, { ...session, connectionId: undefined });
+        expect(synced).toBe(0);
+        expect(knowledgeSlRefsRepository.syncFromWiki).not.toHaveBeenCalled();
+    });
+    it('syncs an empty sl_refs list — clearing any stale rows for that wiki', async () => {
+        const { svc, knowledgeSlRefsRepository } = buildService({
+            readPage: vi.fn().mockResolvedValue({
+                pageKey: 'byol-definition',
+                frontmatter: { summary: 'byol' },
+                content: 'body',
+            }),
+            syncFromWiki: vi.fn().mockResolvedValue({ inserted: 0, deleted: 1 }),
+        });
+        const actions = [{ target: 'wiki', type: 'updated', key: 'byol-definition', detail: '' }];
+        const synced = await svc.reconcileCrossRefs(actions, session);
+        expect(synced).toBe(1);
+        expect(knowledgeSlRefsRepository.syncFromWiki).toHaveBeenCalledWith({
+            wikiPageKey: 'byol-definition',
+            wikiScope: 'GLOBAL',
+            wikiScopeId: null,
+            refs: [],
+        });
+    });
+    it('normalizes dotted sl_refs to bare source names, dedupes (H)', async () => {
+        const { svc, knowledgeSlRefsRepository } = buildService({
+            readPage: vi.fn().mockResolvedValue({
+                pageKey: 'fct-labs-overview',
+                frontmatter: {
+                    summary: 'fct_labs',
+                    sl_refs: ['fct_labs', 'fct_labs.count_lab_orders', 'fct_labs.count_distinct_patients', 'lab_results'],
+                },
+                content: 'body',
+            }),
+            syncFromWiki: vi.fn().mockResolvedValue({ inserted: 2, deleted: 0 }),
+        });
+        const actions = [{ target: 'wiki', type: 'created', key: 'fct-labs-overview', detail: '' }];
+        await svc.reconcileCrossRefs(actions, session);
+        expect(knowledgeSlRefsRepository.syncFromWiki).toHaveBeenCalledWith({
+            wikiPageKey: 'fct-labs-overview',
+            wikiScope: 'GLOBAL',
+            wikiScopeId: null,
+            refs: [
+                { connectionId: 'conn-1', sourceName: 'fct_labs' },
+                { connectionId: 'conn-1', sourceName: 'lab_results' },
+            ],
+        });
+    });
+    it('ignores sl-only actions — the DB index is driven from the wiki side', async () => {
+        const { svc, knowledgeSlRefsRepository } = buildService({});
+        const actions = [{ target: 'sl', type: 'updated', key: 'fct_labs', detail: '' }];
+        const synced = await svc.reconcileCrossRefs(actions, session);
+        expect(synced).toBe(0);
+        expect(knowledgeSlRefsRepository.syncFromWiki).not.toHaveBeenCalled();
+    });
+});
+describe('MemoryAgentService.gateRevertInvalidSources (J3)', () => {
+    // Build a service with the minimal deps the gate needs: semanticLayerService
+    // (readSourceFile, loadSource, writeSource for revert), dataSourcesService
+    // (executeQuery for dry-run), configService (writeFile/deleteFile for revert),
+    // gitService (getFileAtCommit).
+    const buildService = (overrides) => {
+        const semanticLayerService = {
+            readSourceFile: overrides.readSourceFile ?? vi.fn(),
+            isManifestBacked: vi.fn().mockResolvedValue(false),
+        };
+        const connections = {
+            listEnabledConnections: vi.fn().mockResolvedValue([]),
+            getConnectionById: vi.fn().mockResolvedValue({
+                id: 'conn-1',
+                name: 'Warehouse',
+                connectionType: 'POSTGRESQL',
+            }),
+            executeQuery: overrides.executeQuery ?? vi.fn(),
+        };
+        const configService = {
+            writeFile: overrides.writeFile ?? vi.fn().mockResolvedValue({}),
+            deleteFile: overrides.deleteFile ?? vi.fn().mockResolvedValue({}),
+        };
+        const gitService = {
+            getFileAtCommit: overrides.getFileAtCommit ?? vi.fn().mockRejectedValue(new Error('not present')),
+        };
+        const slSourcesRepository = {
+            deleteByConnectionAndName: vi.fn().mockResolvedValue(undefined),
+        };
+        const svc = new MemoryAgentService({
+            settings: {
+                knowledge: { userScopedKnowledgeEnabled: false },
+                slValidation: { probeRowCount: 1 },
+                llm: { memoryIngestionModel: 'test-model' },
+            },
+            promptService: undefined,
+            skillsRegistry: undefined,
+            wikiService: undefined,
+            knowledgeIndex: undefined,
+            knowledgeSlRefs: undefined,
+            semanticLayerService: semanticLayerService,
+            slSearchService: undefined,
+            connections: connections,
+            rootFileStore: configService,
+            gitService: gitService,
+            lockingService: undefined,
+            slSourcesRepository: slSourcesRepository,
+            sessionWorktreeService: undefined,
+            semanticLayerSourceReconciler: undefined,
+            agentRunner: undefined,
+            slValidator: passthroughValidator,
+            toolsetFactory: undefined,
+        });
+        return { svc, semanticLayerService, connections, configService, gitService, slSourcesRepository };
+    };
+    const session = {
+        userId: 'u',
+        chatId: 'c',
+        userMessage: 'test',
+        connectionId: 'conn-1',
+        userScopedEnabled: false,
+        forceGlobalScope: false,
+        touchedSlSources: createTouchedSlSources([{ connectionId: 'conn-1', sourceName: 'broken_source' }]),
+        preHead: null,
+    };
+    it('reverts (deletes) a source whose dry-run fails and drops its action', async () => {
+        const badYaml = `name: broken_source
+source_type: sql
+sql: |
+  SELECT fake_col FROM analytics.x
+grain: [fake_col]
+columns: [{name: fake_col, type: string}]
+measures: []
+joins: []
+`;
+        const { svc, configService } = buildService({
+            readSourceFile: vi.fn().mockResolvedValue({ content: badYaml, path: 'x' }),
+            executeQuery: vi.fn().mockResolvedValue({
+                headers: [],
+                rows: [],
+                totalRows: 0,
+                error: 'Unrecognized name: fake_col',
+            }),
+        });
+        const actions = [
+            { target: 'sl', type: 'created', key: 'broken_source', detail: 'create' },
+            { target: 'wiki', type: 'created', key: 'some_wiki', detail: 'wiki' },
+        ];
+        const localSession = {
+            ...session,
+            touchedSlSources: createTouchedSlSources([{ connectionId: 'conn-1', sourceName: 'broken_source' }]),
+        };
+        const reverted = await svc.gateRevertInvalidSources(localSession, actions);
+        expect(reverted).toEqual(['broken_source']);
+        expect(configService.deleteFile).toHaveBeenCalledWith('semantic-layer/conn-1/broken_source.yaml', expect.any(String), expect.any(String), expect.any(String), { skipLock: true });
+        // Wiki action survives; SL action is scrubbed.
+        expect(actions.map((a) => `${a.target}:${a.key}`)).toEqual(['wiki:some_wiki']);
+        expect(hasTouchedSlSource(localSession.touchedSlSources, 'conn-1', 'broken_source')).toBe(false);
+    });
+    it('leaves a source alone when its dry-run passes', async () => {
+        const goodYaml = `name: good_source
+source_type: sql
+sql: |
+  SELECT id FROM analytics.x
+grain: [id]
+columns: [{name: id, type: string}]
+measures: []
+joins: []
+`;
+        const { svc, configService } = buildService({
+            readSourceFile: vi.fn().mockResolvedValue({ content: goodYaml, path: 'x' }),
+            executeQuery: vi.fn().mockResolvedValue({ headers: ['id'], rows: [], totalRows: 0, error: null }),
+        });
+        const actions = [{ target: 'sl', type: 'created', key: 'good_source', detail: 'create' }];
+        const localSession = {
+            ...session,
+            touchedSlSources: createTouchedSlSources([{ connectionId: 'conn-1', sourceName: 'good_source' }]),
+        };
+        const reverted = await svc.gateRevertInvalidSources(localSession, actions);
+        expect(reverted).toEqual([]);
+        expect(configService.writeFile).not.toHaveBeenCalled();
+        expect(configService.deleteFile).not.toHaveBeenCalled();
+        expect(actions).toHaveLength(1);
+    });
+});

package/dist/context/memory/memory-runs.d.ts

@@ -0,0 +1,55 @@
+import type { MemoryAgentInput, MemoryAgentResult } from '../../context/memory/types.js';
+import type { MemoryAgentService } from '../../context/memory/memory-agent.service.js';
+export type MemoryRunStatus = 'running' | 'done' | 'error';
+export interface MemoryRunRecord {
+    id: string;
+    status: MemoryRunStatus;
+    stage: string;
+    inputHash: string;
+    chatId: string | null;
+    outputSummary: MemoryAgentResult | null;
+    error: string | null;
+}
+export interface MemoryRunStorePort {
+    createRunning(args: {
+        inputHash: string;
+        chatId?: string | null;
+    }): Promise<{
+        id: string;
+    }>;
+    markRunning(id: string, stage: string): Promise<void>;
+    markDone(id: string, outputSummary: MemoryAgentResult): Promise<void>;
+    markError(id: string, error: string): Promise<void>;
+    findById(id: string): Promise<MemoryRunRecord | null>;
+}
+export interface MemoryIngestServiceDeps {
+    memoryAgent: Pick<MemoryAgentService, 'ingest'>;
+    runs: MemoryRunStorePort;
+}
+export interface MemoryIngestStartResult {
+    runId: string;
+}
+export interface MemoryIngestStatus {
+    runId: string;
+    status: MemoryRunStatus;
+    stage: string;
+    done: boolean;
+    captured: {
+        wiki: string[];
+        sl: string[];
+        xrefs: string[];
+    };
+    error: string | null;
+    commitHash: string | null;
+    skillsLoaded: string[];
+    signalDetected: boolean;
+}
+export declare class MemoryIngestService {
+    private readonly deps;
+    private readonly inFlight;
+    constructor(deps: MemoryIngestServiceDeps);
+    ingest(input: MemoryAgentInput): Promise<MemoryIngestStartResult>;
+    waitForRun(runId: string): Promise<void>;
+    private runIngest;
+    status(runId: string): Promise<MemoryIngestStatus | null>;
+}

package/dist/context/memory/memory-runtime-assets.test.js

@@ -0,0 +1,162 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { PromptService } from '../../context/prompts/prompt.service.js';
+import { SkillsRegistryService } from '../../context/skills/skills-registry.service.js';
+import { DEFAULT_SKILL_NAMES, promptNameFor } from '../../context/memory/capture-signals.js';
+const promptsDir = fileURLToPath(new URL('../../prompts', import.meta.url));
+const skillsDir = fileURLToPath(new URL('../../skills', import.meta.url));
+const memorySourceTypes = ['research', 'external_ingest', 'backfill'];
+const expectedSkillHeadings = {
+    wiki_capture: '# Wiki Capture',
+    sl: '# Semantic Layer',
+    sl_capture: '# Semantic Layer',
+};
+const expectedAdapterSkillHeadings = {
+    historic_sql_patterns: '# Historic SQL Patterns',
+    historic_sql_table_digest: '# Historic SQL Table Digest',
+    live_database_ingest: '# Live Database Ingest',
+    looker_ingest: '# Looker Runtime Ingest',
+    lookml_ingest: '# LookML to KTX Semantic Layer',
+    metabase_ingest: '# Metabase to KTX Semantic Layer',
+    metricflow_ingest: '# MetricFlow to KTX Semantic Layer',
+};
+const verificationWriterSkills = [
+    'notion_synthesize',
+    'dbt_ingest',
+    'lookml_ingest',
+    'looker_ingest',
+    'metabase_ingest',
+    'metricflow_ingest',
+    'live_database_ingest',
+    'historic_sql_table_digest',
+    'historic_sql_patterns',
+    'wiki_capture',
+    'sl_capture',
+];
+function forbiddenProductPattern() {
+    return new RegExp([['Kae', 'lio'].join(''), ['kae', 'lio'].join(''), ['KAE', 'LIO_'].join('')].join('|'));
+}
+function sqlExecutionCallBlocks(body) {
+    const blocks = [];
+    const marker = 'sql_execution({';
+    let offset = 0;
+    while (offset < body.length) {
+        const start = body.indexOf(marker, offset);
+        if (start === -1) {
+            break;
+        }
+        const end = body.indexOf('})', start + marker.length);
+        blocks.push(body.slice(start, end === -1 ? start + marker.length : end + 2));
+        offset = start + marker.length;
+    }
+    return blocks;
+}
+describe('memory runtime assets', () => {
+    it('packages every memory-agent base prompt referenced by promptNameFor()', async () => {
+        const prompts = new PromptService({ promptsDir, partials: [] });
+        for (const sourceType of memorySourceTypes) {
+            const promptName = promptNameFor(sourceType);
+            const prompt = await prompts.loadPrompt(promptName);
+            expect(prompt).toContain('<role>');
+            expect(prompt).toContain('<workflow>');
+            expect(prompt).not.toMatch(forbiddenProductPattern());
+        }
+    });
+    it('packages the default memory capture skills referenced by DEFAULT_SKILL_NAMES', async () => {
+        const registry = new SkillsRegistryService({ skillsDir });
+        const skills = await registry.listSkills([...DEFAULT_SKILL_NAMES], 'memory_agent');
+        expect(skills.map((skill) => skill.name).sort()).toEqual(['sl', 'sl_capture', 'wiki_capture']);
+        for (const skill of skills) {
+            const body = await readFile(join(skill.path, 'SKILL.md'), 'utf-8');
+            const expectedHeading = expectedSkillHeadings[skill.name];
+            expect(expectedHeading).toBeDefined();
+            expect(body).toContain(expectedHeading);
+            expect(body).not.toMatch(forbiddenProductPattern());
+        }
+    });
+    it('keeps memory-only capture skills hidden from research callers', async () => {
+        const registry = new SkillsRegistryService({ skillsDir });
+        const skills = await registry.listSkills([...DEFAULT_SKILL_NAMES], 'research');
+        expect(skills.map((skill) => skill.name)).toEqual(['sl']);
+    });
+    it('packages ingest adapter skills referenced by bundled adapters', async () => {
+        const registry = new SkillsRegistryService({ skillsDir });
+        const skillNames = Object.keys(expectedAdapterSkillHeadings);
+        const skills = await registry.listSkills(skillNames, 'memory_agent');
+        expect(skills.map((skill) => skill.name).sort()).toEqual([...skillNames].sort());
+        for (const skill of skills) {
+            const body = await readFile(join(skill.path, 'SKILL.md'), 'utf-8');
+            expect(body).toContain(expectedAdapterSkillHeadings[skill.name]);
+            expect(body).not.toMatch(forbiddenProductPattern());
+        }
+    });
+    it('ships Looker runtime ingest guidance for warehouse target SL writes', async () => {
+        const body = await readFile(join(skillsDir, 'looker_ingest', 'SKILL.md'), 'utf-8');
+        expect(body).toContain('targetWarehouseConnectionId');
+        expect(body).toContain('targetTable.ok === true');
+        expect(body).toContain('targetTable.canonicalTable');
+        expect(body).toContain('source_tables preflight');
+        expect(body).toContain('emit_unmapped_fallback');
+        expect(body).toContain('no_connection_mapping');
+        expect(body).not.toContain('a standalone SL source only when raw evidence contains enough table or SQL structure');
+    });
+    it('ships Metabase guidance that avoids invalid joins for SQL-only card outputs', async () => {
+        const body = await readFile(join(skillsDir, 'metabase_ingest', 'SKILL.md'), 'utf-8');
+        expect(body).toContain('Do not declare a KTX join just because the card SQL joins that table internally');
+        expect(body).toContain('only when the card output exposes a local key that matches the target source grain');
+        expect(body).toContain('If `sl_discover` resolves the table, it is not outside the manifest');
+        expect(body).toContain('reason: "parse_error"');
+        expect(body).not.toContain('Tables outside the manifest');
+        expect(body).not.toContain('reason: "metabase_sql_untranslated"');
+    });
+    it('ships Notion guidance for physical-table fallbacks and duplicate wiki reconciliation', async () => {
+        const body = await readFile(join(skillsDir, 'notion_synthesize', 'SKILL.md'), 'utf-8');
+        expect(body).toContain('Notion `dataSourceCount` counts Notion databases/data sources only');
+        expect(body).toContain('Search existing wiki pages for the same `tables:` or `sl_refs:` frontmatter');
+        expect(body).toContain('no_physical_table');
+    });
+    it('packages LookML connection-mismatch SL gate guidance', async () => {
+        const body = await readFile(join(skillsDir, 'lookml_ingest', 'SKILL.md'), 'utf-8');
+        expect(body).toContain('[LOOKML SL WRITES DISALLOWED]');
+        expect(body).toContain('lookml_connection_mismatch');
+        expect(body).toContain('Do not call `sl_write_source` or `sl_edit_source`');
+        expect(body).toContain('LookML writes target the run connection directly');
+    });
+    it('ships identifier verification protocol in every synthesis writer skill', async () => {
+        for (const skillName of verificationWriterSkills) {
+            const body = await readFile(join(skillsDir, skillName, 'SKILL.md'), 'utf-8');
+            expect(body).toContain('## Identifier Verification Protocol');
+            expect(body).toMatch(/discover_data|entity_details/);
+        }
+    });
+    it('does not ship stale warehouse verification tool names or fictional identifiers', async () => {
+        for (const skillName of verificationWriterSkills) {
+            const body = await readFile(join(skillsDir, skillName, 'SKILL.md'), 'utf-8');
+            expect(body).not.toContain('orbit_analytics.customer');
+            expect(body).not.toContain('wiki_sl_search');
+            expect(body).not.toContain('sl_describe_table');
+        }
+    });
+    it('ships only the KTX connectionId sql_execution call shape in writer guidance', async () => {
+        const shared = await readFile(join(skillsDir, '_shared', 'identifier-verification.md'), 'utf-8');
+        const bodies = [{ name: '_shared/identifier-verification.md', body: shared }];
+        expect(shared).toContain('sql_execution({connectionId, sql: "SELECT DISTINCT');
+        expect(shared).toContain('sql_execution({connectionId, sql: "SELECT 1 FROM');
+        for (const skillName of verificationWriterSkills) {
+            const body = await readFile(join(skillsDir, skillName, 'SKILL.md'), 'utf-8');
+            bodies.push({ name: `${skillName}/SKILL.md`, body });
+            expect(body).toContain('sql_execution({connectionId');
+            expect(body).not.toContain('sql_execution({ sql');
+            expect(body).not.toContain('session shape');
+            expect(body).not.toContain('connection is already pinned by the ingest session');
+        }
+        for (const { name, body } of bodies) {
+            const calls = sqlExecutionCallBlocks(body);
+            expect(calls.length, `${name} should contain sql_execution guidance`).toBeGreaterThan(0);
+            expect(calls.filter((call) => !call.includes('connectionId')), `${name} has sql_execution calls without connectionId`).toEqual([]);
+            expect(body, `${name} has a connectionless multiline sql_execution call`).not.toMatch(/sql_execution\(\{\s*sql\s*:/);
+        }
+    });
+});