@kaelio/ktx 0.0.0 → 0.1.0-rc.1

package/node_modules/@ktx/context/dist/ingest/tools/tool-transcript-summary.test.js

@@ -0,0 +1,141 @@
+import { describe, expect, it } from 'vitest';
+import { createMutableToolTranscriptSummary, recordToolTranscriptEntry } from './tool-transcript-summary.js';
+function entry(overrides) {
+    return {
+        ts: '2026-05-11T00:00:00.000Z',
+        wuKey: 'wu-1',
+        toolName: 'wiki_write',
+        durationMs: 1,
+        input: {},
+        ...overrides,
+    };
+}
+describe('tool transcript summaries', () => {
+    it('keeps recovered wiki_write structured failures out of fatal failures', () => {
+        const summary = createMutableToolTranscriptSummary('wu-1', '/tmp/wu-1.jsonl');
+        recordToolTranscriptEntry(summary, entry({
+            input: { key: 'orbit-customers' },
+            output: { structured: { success: false, key: 'orbit-customers' } },
+        }));
+        recordToolTranscriptEntry(summary, entry({
+            input: { key: 'orbit-customers' },
+            output: { structured: { success: true, key: 'orbit-customers' } },
+        }));
+        expect(summary.errorCount).toBe(1);
+        expect(summary.fatalErrorCount).toBe(0);
+    });
+    it('treats a suggested flat wiki key retry as recovery for an invalid nested key', () => {
+        const summary = createMutableToolTranscriptSummary('wu-1', '/tmp/wu-1.jsonl');
+        recordToolTranscriptEntry(summary, entry({
+            input: { key: 'historic-sql/top-accounts-by-contract-arr' },
+            output: { structured: { success: false, key: 'historic-sql/top-accounts-by-contract-arr' } },
+        }));
+        recordToolTranscriptEntry(summary, entry({
+            input: { key: 'historic-sql-top-accounts-by-contract-arr' },
+            output: { structured: { success: true, key: 'historic-sql-top-accounts-by-contract-arr' } },
+        }));
+        expect(summary.errorCount).toBe(1);
+        expect(summary.fatalErrorCount).toBe(0);
+    });
+    it('counts unrecovered wiki_remove structured failures as fatal transcript errors', () => {
+        const summary = createMutableToolTranscriptSummary('reconcile', '/tmp/reconcile.jsonl');
+        recordToolTranscriptEntry(summary, {
+            ts: '2026-05-11T00:00:00.000Z',
+            wuKey: 'reconcile',
+            toolCallId: 'remove-1',
+            toolName: 'wiki_remove',
+            durationMs: 1,
+            input: { key: 'duplicate-page' },
+            output: { structured: { success: false, key: 'duplicate-page' } },
+        });
+        expect(summary.errorCount).toBe(1);
+        expect(summary.fatalErrorCount).toBe(1);
+    });
+    it('keeps unrecovered structured write failures fatal', () => {
+        const summary = createMutableToolTranscriptSummary('wu-1', '/tmp/wu-1.jsonl');
+        recordToolTranscriptEntry(summary, entry({
+            input: { key: 'orbit-customers' },
+            output: { structured: { success: false, key: 'orbit-customers' } },
+        }));
+        expect(summary.errorCount).toBe(1);
+        expect(summary.fatalErrorCount).toBe(1);
+    });
+    it('treats a later sl_edit_source success as recovery for the same SL source', () => {
+        const summary = createMutableToolTranscriptSummary('wu-1', '/tmp/wu-1.jsonl');
+        recordToolTranscriptEntry(summary, entry({
+            toolName: 'sl_write_source',
+            input: { connectionId: 'warehouse', sourceName: 'orbit_customers' },
+            output: { structured: { success: false, sourceName: 'orbit_customers' } },
+        }));
+        recordToolTranscriptEntry(summary, entry({
+            toolName: 'sl_edit_source',
+            input: { connectionId: 'warehouse', sourceName: 'orbit_customers' },
+            output: { structured: { success: true, sourceName: 'orbit_customers' } },
+        }));
+        expect(summary.errorCount).toBe(1);
+        expect(summary.fatalErrorCount).toBe(0);
+    });
+    it('treats explicit unmapped fallback as recovery for guarded SL write failures', () => {
+        const summary = createMutableToolTranscriptSummary('wu-1', '/tmp/wu-1.jsonl');
+        recordToolTranscriptEntry(summary, entry({
+            toolName: 'sl_write_source',
+            input: { connectionId: 'dbt-main', sourceName: 'stg_accounts' },
+            output: { structured: { success: false, sourceName: 'stg_accounts' } },
+        }));
+        recordToolTranscriptEntry(summary, entry({
+            toolName: 'emit_unmapped_fallback',
+            input: { rawPath: 'models/schema.yml', reason: 'no_physical_table', tableRef: 'stg_accounts', fallback: 'wiki_only' },
+            output: 'recorded unmapped fallback for models/schema.yml (wiki_only)',
+        }));
+        expect(summary.errorCount).toBe(1);
+        expect(summary.fatalErrorCount).toBe(0);
+    });
+    it('treats an untargeted unmapped fallback as recovery when there is only one pending SL failure', () => {
+        const summary = createMutableToolTranscriptSummary('wu-1', '/tmp/wu-1.jsonl');
+        recordToolTranscriptEntry(summary, entry({
+            toolName: 'sl_write_source',
+            input: { connectionId: 'dbt-main', sourceName: 'stg_accounts' },
+            output: { structured: { success: false, sourceName: 'stg_accounts' } },
+        }));
+        recordToolTranscriptEntry(summary, entry({
+            toolName: 'emit_unmapped_fallback',
+            input: { rawPath: 'models/schema.yml', reason: 'no_physical_table', fallback: 'wiki_only' },
+            output: 'recorded unmapped fallback for models/schema.yml (wiki_only)',
+        }));
+        expect(summary.errorCount).toBe(1);
+        expect(summary.fatalErrorCount).toBe(0);
+    });
+    it('keeps unrelated SL write failures fatal when one source gets an unmapped fallback', () => {
+        const summary = createMutableToolTranscriptSummary('wu-1', '/tmp/wu-1.jsonl');
+        recordToolTranscriptEntry(summary, entry({
+            toolName: 'sl_write_source',
+            input: { connectionId: 'dbt-main', sourceName: 'stg_accounts' },
+            output: { structured: { success: false, sourceName: 'stg_accounts' } },
+        }));
+        recordToolTranscriptEntry(summary, entry({
+            toolName: 'sl_write_source',
+            input: { connectionId: 'dbt-main', sourceName: 'stg_orders' },
+            output: { structured: { success: false, sourceName: 'stg_orders' } },
+        }));
+        recordToolTranscriptEntry(summary, entry({
+            toolName: 'emit_unmapped_fallback',
+            input: { rawPath: 'models/schema.yml', reason: 'no_physical_table', tableRef: 'stg_accounts', fallback: 'wiki_only' },
+            output: 'recorded unmapped fallback for models/schema.yml (wiki_only)',
+        }));
+        expect(summary.errorCount).toBe(2);
+        expect(summary.fatalErrorCount).toBe(1);
+    });
+    it('keeps thrown tool errors fatal even after a successful write', () => {
+        const summary = createMutableToolTranscriptSummary('wu-1', '/tmp/wu-1.jsonl');
+        recordToolTranscriptEntry(summary, entry({
+            input: { key: 'orbit-customers' },
+            error: { message: 'tool crashed' },
+        }));
+        recordToolTranscriptEntry(summary, entry({
+            input: { key: 'orbit-customers' },
+            output: { structured: { success: true, key: 'orbit-customers' } },
+        }));
+        expect(summary.errorCount).toBe(1);
+        expect(summary.fatalErrorCount).toBe(1);
+    });
+});

package/node_modules/@ktx/context/dist/ingest/tools/verification-ledger.tool.d.ts

@@ -0,0 +1,14 @@
+import type { KtxRuntimeToolSet } from '../../llm/index.js';
+interface VerificationLedgerEntry {
+    summary: string;
+    verifiedIdentifiers: string[];
+    unverifiedIdentifiers: string[];
+    notes?: string;
+}
+export interface VerificationLedgerState {
+    entries: VerificationLedgerEntry[];
+}
+export declare const VERIFICATION_LEDGER_PROMPT = "<pre_write_verification>\nBefore any durable wiki, semantic-layer, or unmapped-fallback write (wiki_write, wiki_remove, sl_write_source, sl_edit_source, emit_unmapped_fallback), call record_verification_ledger.\nThe ledger is a model-authored checkpoint, not a deterministic parser gate. Summarize the verification protocol from the loaded skill, list identifiers verified with discover_data/entity_details/sql_execution, and list anything intentionally left unverified. If the write contains no warehouse identifiers, say that explicitly.\nIf a write tool returns verification_ledger_required, complete the ledger and retry the write.\n</pre_write_verification>";
+export declare function createVerificationLedgerState(): VerificationLedgerState;
+export declare function withVerificationLedger(tools: KtxRuntimeToolSet, state: VerificationLedgerState): KtxRuntimeToolSet;
+export {};

package/node_modules/@ktx/context/dist/ingest/tools/verification-ledger.tool.js

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+const verificationLedgerInputSchema = z.object({
+    summary: z.string().min(1).max(2000),
+    verifiedIdentifiers: z.array(z.string().min(1)).max(100).default([]),
+    unverifiedIdentifiers: z.array(z.string().min(1)).max(100).default([]),
+    notes: z.string().max(2000).optional(),
+});
+const WRITE_TOOL_NAMES = new Set([
+    'wiki_write',
+    'wiki_remove',
+    'sl_write_source',
+    'sl_edit_source',
+    'emit_unmapped_fallback',
+]);
+export const VERIFICATION_LEDGER_PROMPT = `<pre_write_verification>
+Before any durable wiki, semantic-layer, or unmapped-fallback write (wiki_write, wiki_remove, sl_write_source, sl_edit_source, emit_unmapped_fallback), call record_verification_ledger.
+The ledger is a model-authored checkpoint, not a deterministic parser gate. Summarize the verification protocol from the loaded skill, list identifiers verified with discover_data/entity_details/sql_execution, and list anything intentionally left unverified. If the write contains no warehouse identifiers, say that explicitly.
+If a write tool returns verification_ledger_required, complete the ledger and retry the write.
+</pre_write_verification>`;
+export function createVerificationLedgerState() {
+    return { entries: [] };
+}
+export function withVerificationLedger(tools, state) {
+    const wrapped = {};
+    for (const [name, original] of Object.entries(tools)) {
+        if (!WRITE_TOOL_NAMES.has(name) || typeof original.execute !== 'function') {
+            wrapped[name] = original;
+            continue;
+        }
+        const originalExecute = original.execute;
+        const guardedExecute = async (input) => {
+            if (state.entries.length === 0) {
+                return verificationRequiredOutput(name);
+            }
+            return originalExecute(input);
+        };
+        wrapped[name] = { ...original, execute: guardedExecute };
+    }
+    wrapped.record_verification_ledger = createRecordVerificationLedgerTool(state);
+    return wrapped;
+}
+function createRecordVerificationLedgerTool(state) {
+    return {
+        name: 'record_verification_ledger',
+        description: 'Record the pre-write verification ledger required by loaded ingest skills. Call this before wiki/SL/fallback writes to state what was verified, which tool calls support it, and what remains intentionally unverified.',
+        inputSchema: verificationLedgerInputSchema,
+        execute: async (input) => {
+            const entry = verificationLedgerInputSchema.parse(input);
+            state.entries.push(entry);
+            return {
+                markdown: `Verification ledger recorded. Summary: ${entry.summary}\n` +
+                    `Verified identifiers: ${entry.verifiedIdentifiers.length ? entry.verifiedIdentifiers.join(', ') : '(none)'}\n` +
+                    `Unverified identifiers: ${entry.unverifiedIdentifiers.length ? entry.unverifiedIdentifiers.join(', ') : '(none)'}`,
+                structured: { success: true, entry },
+            };
+        },
+    };
+}
+function verificationRequiredOutput(toolName) {
+    return {
+        markdown: `Pre-write verification required before calling ${toolName}. ` +
+            'Call record_verification_ledger first. In the ledger, summarize the loaded skill protocol you followed, ' +
+            'list identifiers verified via discover_data/entity_details/sql_execution, and list any identifiers intentionally left unverified. ' +
+            'If the write contains no warehouse identifiers, say that explicitly in the ledger summary.',
+        structured: {
+            success: false,
+            reason: 'verification_ledger_required',
+            toolName,
+        },
+    };
+}

package/node_modules/@ktx/context/dist/ingest/tools/warehouse-verification/discover-data.tool.d.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { WarehouseCatalogService, type RawSchemaHit } from '../../../scan/warehouse-catalog.js';
+import { BaseTool, type ToolContext, type ToolOutput } from '../../../tools/index.js';
+declare const discoverDataInputSchema: z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    connectionId: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    sourceName: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type DiscoverDataInput = z.input<typeof discoverDataInputSchema>;
+export interface DiscoverDataStructured {
+    wiki: unknown | null;
+    sl: unknown | null;
+    raw: {
+        hits: RawSchemaHit[];
+    } | null;
+}
+interface DiscoverDataDeps {
+    wikiSearchTool: BaseTool;
+    slDiscoverTool: BaseTool;
+    catalogFactory: (context: ToolContext) => WarehouseCatalogService;
+}
+export declare class DiscoverDataTool extends BaseTool<typeof discoverDataInputSchema> {
+    private readonly deps;
+    readonly name = "discover_data";
+    constructor(deps: DiscoverDataDeps);
+    get description(): string;
+    get inputSchema(): z.ZodObject<{
+        query: z.ZodOptional<z.ZodString>;
+        connectionId: z.ZodOptional<z.ZodString>;
+        limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        sourceName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    call(input: DiscoverDataInput, context: ToolContext): Promise<ToolOutput<DiscoverDataStructured>>;
+}
+export {};

package/node_modules/@ktx/context/dist/ingest/tools/warehouse-verification/discover-data.tool.js

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+import { BaseTool } from '../../../tools/index.js';
+const discoverDataInputSchema = z.object({
+    query: z.string().optional(),
+    connectionId: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/).optional(),
+    limit: z.number().int().positive().max(50).optional().default(10),
+    sourceName: z.string().optional(),
+}).strict();
+function totalFound(structured) {
+    return typeof structured === 'object' &&
+        structured !== null &&
+        'totalFound' in structured &&
+        typeof structured.totalFound === 'number'
+        ? structured.totalFound
+        : 0;
+}
+function totalSources(structured) {
+    return typeof structured === 'object' &&
+        structured !== null &&
+        'totalSources' in structured &&
+        typeof structured.totalSources === 'number'
+        ? structured.totalSources
+        : 0;
+}
+function allowedConnectionNames(context) {
+    return context.session?.allowedConnectionNames ?? null;
+}
+export class DiscoverDataTool extends BaseTool {
+    deps;
+    name = 'discover_data';
+    constructor(deps) {
+        super();
+        this.deps = deps;
+    }
+    get description() {
+        return 'Discover existing wiki pages, semantic layer sources, and raw warehouse schema hits before writing ingest output.';
+    }
+    get inputSchema() {
+        return discoverDataInputSchema;
+    }
+    async call(input, context) {
+        const allowed = allowedConnectionNames(context);
+        if (input.connectionId && allowed && !allowed.has(input.connectionId)) {
+            return {
+                markdown: `Connection "${input.connectionId}" is not available to this ingest stage.`,
+                structured: { wiki: null, sl: null, raw: null },
+            };
+        }
+        if (input.sourceName) {
+            const sl = await this.deps.slDiscoverTool.call({ sourceName: input.sourceName, connectionId: input.connectionId }, context);
+            return { markdown: sl.markdown, structured: { wiki: null, sl: sl.structured, raw: null } };
+        }
+        const query = input.query?.trim() || '';
+        const limit = input.limit ?? 10;
+        const parts = [];
+        let wiki = null;
+        let sl = null;
+        let raw = null;
+        if (query) {
+            const wikiResult = await this.deps.wikiSearchTool.call({ query, limit }, context);
+            if (totalFound(wikiResult.structured) > 0) {
+                parts.push('## Wiki Pages', '> use `wiki_read(blockKey)` for full content', wikiResult.markdown, '');
+                wiki = wikiResult.structured;
+            }
+        }
+        const slResult = await this.deps.slDiscoverTool.call({ query: query || undefined, connectionId: input.connectionId }, context);
+        if (totalSources(slResult.structured) > 0) {
+            parts.push('## Semantic Layer Sources', '> use `sl_read_source(sourceName)` for the YAML, or `entity_details` for warehouse-shape details', slResult.markdown, '');
+            sl = slResult.structured;
+        }
+        const catalog = this.deps.catalogFactory(context);
+        const connections = input.connectionId ? [input.connectionId] : [...(allowed ?? [])].sort();
+        const rawHits = [];
+        for (const connectionId of connections) {
+            rawHits.push(...(await catalog.searchByName(connectionId, query, limit)));
+        }
+        if (rawHits.length > 0) {
+            parts.push('## Raw Warehouse Schema', '> use `entity_details({connectionId, targets: [{display}]})` for full DDL + sample values');
+            parts.push(rawHits
+                .slice(0, limit)
+                .map((hit) => `- ${hit.kind}: ${hit.display} [connectionId=${hit.connectionId}] (matched on ${hit.matchedOn}) - ` +
+                `follow up with \`entity_details({connectionId: "${hit.connectionId}", targets: [{display: "${hit.display}"}]})\``)
+                .join('\n'));
+            raw = { hits: rawHits.slice(0, limit) };
+        }
+        if (parts.length === 0) {
+            return {
+                markdown: `No matches for "${query}" across wiki, semantic layer, or raw warehouse schema. Try broader terms; this concept may not exist yet.`,
+                structured: { wiki, sl, raw },
+            };
+        }
+        return { markdown: parts.join('\n'), structured: { wiki, sl, raw } };
+    }
+}

package/node_modules/@ktx/context/dist/ingest/tools/warehouse-verification/discover-data.tool.test.d.ts

@@ -0,0 +1 @@
+export {};

package/node_modules/@ktx/context/dist/ingest/tools/warehouse-verification/discover-data.tool.test.js

@@ -0,0 +1,107 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { DiscoverDataTool } from './discover-data.tool.js';
+describe('DiscoverDataTool', () => {
+    const wikiSearchTool = { call: vi.fn() };
+    const slDiscoverTool = { call: vi.fn() };
+    const catalog = { searchByName: vi.fn() };
+    const context = {
+        sourceId: 'ingest',
+        messageId: 'm1',
+        userId: 'system',
+        session: { allowedConnectionNames: new Set(['warehouse']) },
+    };
+    const tool = new DiscoverDataTool({
+        wikiSearchTool,
+        slDiscoverTool,
+        catalogFactory: () => catalog,
+    });
+    beforeEach(() => {
+        wikiSearchTool.call.mockReset();
+        slDiscoverTool.call.mockReset();
+        catalog.searchByName.mockReset();
+        wikiSearchTool.call.mockResolvedValue({
+            markdown: '- orders wiki',
+            structured: { totalFound: 1, results: [{ key: 'orders' }] },
+        });
+        slDiscoverTool.call.mockResolvedValue({
+            markdown: '- orders source',
+            structured: { totalSources: 1, sources: [{ sourceName: 'orders' }] },
+        });
+        catalog.searchByName.mockResolvedValue([
+            {
+                kind: 'table',
+                connectionId: 'warehouse',
+                ref: { catalog: null, db: 'public', name: 'orders' },
+                display: 'public.orders',
+                matchedOn: 'name',
+            },
+        ]);
+    });
+    it('groups wiki, semantic layer, and raw schema hits with routing hints', async () => {
+        const result = await tool.call({ query: 'orders', connectionId: 'warehouse', limit: 5 }, context);
+        expect(result.markdown).toContain('## Wiki Pages');
+        expect(result.markdown).toContain('use `wiki_read(blockKey)` for full content');
+        expect(result.markdown).toContain('## Semantic Layer Sources');
+        expect(result.markdown).toContain('use `sl_read_source(sourceName)` for the YAML');
+        expect(result.markdown).toContain('## Raw Warehouse Schema');
+        expect(result.markdown).toContain('use `entity_details({connectionId, targets: [{display}]})`');
+        expect(result.structured.raw?.hits).toHaveLength(1);
+    });
+    it('includes connectionId on raw schema hits so entity_details can follow up', async () => {
+        const multiConnectionContext = {
+            ...context,
+            session: { allowedConnectionNames: new Set(['warehouse', 'analytics']) },
+        };
+        catalog.searchByName.mockImplementation(async (connectionId, query) => [
+            {
+                kind: 'table',
+                connectionId,
+                ref: { catalog: null, db: 'public', name: `${connectionId}_${query}` },
+                display: `public.${connectionId}_${query}`,
+                matchedOn: 'name',
+            },
+        ]);
+        const result = await tool.call({ query: 'orders', limit: 10 }, multiConnectionContext);
+        expect(catalog.searchByName).toHaveBeenCalledWith('analytics', 'orders', 10);
+        expect(catalog.searchByName).toHaveBeenCalledWith('warehouse', 'orders', 10);
+        expect(result.markdown).toContain('connectionId=analytics');
+        expect(result.markdown).toContain('connectionId=warehouse');
+        expect(result.markdown).toContain('entity_details({connectionId: "analytics", targets: [{display: "public.analytics_orders"}]})');
+        expect(result.structured.raw?.hits.map((hit) => hit.connectionId)).toEqual(['analytics', 'warehouse']);
+    });
+    it('refuses explicit out-of-scope connection names', async () => {
+        const result = await tool.call({ query: 'orders', connectionId: 'billing' }, context);
+        expect(result.markdown).toContain('Connection "billing" is not available to this ingest stage.');
+        expect(result.structured).toEqual({ wiki: null, sl: null, raw: null });
+        expect(wikiSearchTool.call).not.toHaveBeenCalled();
+        expect(slDiscoverTool.call).not.toHaveBeenCalled();
+        expect(catalog.searchByName).not.toHaveBeenCalled();
+    });
+    it('delegates sourceName inspect mode to sl_discover only', async () => {
+        slDiscoverTool.call.mockResolvedValueOnce({
+            markdown: 'source detail',
+            structured: { sourceName: 'orders' },
+        });
+        const result = await tool.call({ sourceName: 'orders', connectionId: 'warehouse' }, context);
+        expect(slDiscoverTool.call).toHaveBeenCalledWith({ sourceName: 'orders', connectionId: 'warehouse' }, context);
+        expect(wikiSearchTool.call).not.toHaveBeenCalled();
+        expect(catalog.searchByName).not.toHaveBeenCalled();
+        expect(result.markdown).toContain('source detail');
+    });
+    it('returns the empty-state message when all sections are empty', async () => {
+        wikiSearchTool.call.mockResolvedValueOnce({ markdown: '', structured: { totalFound: 0, results: [] } });
+        slDiscoverTool.call.mockResolvedValueOnce({ markdown: '', structured: { totalSources: 0, sources: [] } });
+        catalog.searchByName.mockResolvedValueOnce([]);
+        const result = await tool.call({ query: 'customer source', connectionId: 'warehouse' }, context);
+        expect(result.markdown).toContain('No matches for "customer source" across wiki, semantic layer, or raw warehouse schema.');
+    });
+    it('uses connectionId as the optional connection filter', () => {
+        const legacyConnectionField = ['connection', 'Name'].join('');
+        expect(tool.parseInput({ query: 'orders', connectionId: 'warehouse', limit: 5 })).toEqual({
+            query: 'orders',
+            connectionId: 'warehouse',
+            limit: 5,
+        });
+        expect(() => tool.parseInput({ query: 'orders', [legacyConnectionField]: 'warehouse', limit: 5 })).toThrow();
+    });
+});

package/node_modules/@ktx/context/dist/ingest/tools/warehouse-verification/entity-details.tool.d.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import type { KtxTableRef } from '../../../scan/types.js';
+import { WarehouseCatalogService, type TableDetail } from '../../../scan/warehouse-catalog.js';
+import { BaseTool, type ToolContext, type ToolOutput } from '../../../tools/index.js';
+declare const entityDetailsInputSchema: z.ZodObject<{
+    connectionId: z.ZodString;
+    targets: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        display: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        catalog: z.ZodNullable<z.ZodString>;
+        db: z.ZodNullable<z.ZodString>;
+        name: z.ZodString;
+        column: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>;
+}, z.core.$strict>;
+type EntityDetailsInput = z.infer<typeof entityDetailsInputSchema>;
+export interface EntityDetailsStructured {
+    resolved: TableDetail[];
+    missing: Array<{
+        target: unknown;
+        candidates: KtxTableRef[];
+    }>;
+    scanAvailable: boolean;
+}
+export declare class EntityDetailsTool extends BaseTool<typeof entityDetailsInputSchema> {
+    private readonly catalogFactory;
+    readonly name = "entity_details";
+    constructor(catalogFactory: (context: ToolContext) => WarehouseCatalogService);
+    get description(): string;
+    get inputSchema(): z.ZodObject<{
+        connectionId: z.ZodString;
+        targets: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            display: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            catalog: z.ZodNullable<z.ZodString>;
+            db: z.ZodNullable<z.ZodString>;
+            name: z.ZodString;
+            column: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+    }, z.core.$strict>;
+    call(input: EntityDetailsInput, context: ToolContext): Promise<ToolOutput<EntityDetailsStructured>>;
+}
+export {};

package/node_modules/@ktx/context/dist/ingest/tools/warehouse-verification/entity-details.tool.js

@@ -0,0 +1,137 @@
+import { z } from 'zod';
+import { BaseTool } from '../../../tools/index.js';
+const targetSchema = z.union([
+    z.object({ display: z.string().min(1) }),
+    z.object({
+        catalog: z.string().nullable(),
+        db: z.string().nullable(),
+        name: z.string().min(1),
+        column: z.string().optional(),
+    }),
+]);
+const entityDetailsInputSchema = z.object({
+    connectionId: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/),
+    targets: z.array(targetSchema).min(1).max(50),
+}).strict();
+function allowedConnectionNames(context) {
+    return context.session?.allowedConnectionNames ?? null;
+}
+function targetLabel(target) {
+    if ('display' in target) {
+        return target.display;
+    }
+    return [target.catalog, target.db, target.name, target.column].filter((part) => !!part).join('.');
+}
+function appendMissingTargetMarkdown(parts, target, candidates) {
+    parts.push(`Not found in scan: ${targetLabel(target)}`);
+    if (candidates.length > 0) {
+        parts.push(`Closest matches: ${candidates.map((candidate) => candidate.name).join(', ')}`);
+    }
+}
+async function resolveTarget(catalog, connectionId, target) {
+    if ('display' in target) {
+        return catalog.resolveDisplayTarget(connectionId, target.display);
+    }
+    const candidateResolution = await catalog.resolveDisplayTarget(connectionId, targetLabel(target));
+    return {
+        resolved: {
+            catalog: target.catalog,
+            db: target.db,
+            name: target.name,
+            column: target.column,
+        },
+        candidates: candidateResolution.candidates,
+    };
+}
+function sampleText(values) {
+    return values.length > 0 ? ` - sample: ${JSON.stringify(values.slice(0, 10))}` : '';
+}
+function appendTableMarkdown(parts, detail, columnName) {
+    const columns = columnName ? detail.columns.filter((column) => column.name === columnName) : detail.columns;
+    parts.push(`### ${detail.display}`);
+    parts.push(`Type: ${detail.kind} | Native columns: ${detail.columns.length}`);
+    if (detail.description || detail.comment) {
+        parts.push(`Description: ${detail.description ?? detail.comment}`);
+    }
+    parts.push('', 'Columns:');
+    for (const column of columns) {
+        const pk = column.primaryKey ? ', PK' : '';
+        parts.push(`- ${column.name} (${column.nativeType}, nullable=${column.nullable}${pk})${sampleText(column.sampleValues)}`);
+    }
+    parts.push('');
+}
+function findColumn(detail, columnName) {
+    const normalized = columnName.toLowerCase();
+    return detail.columns.find((column) => column.name.toLowerCase() === normalized) ?? null;
+}
+export class EntityDetailsTool extends BaseTool {
+    catalogFactory;
+    name = 'entity_details';
+    constructor(catalogFactory) {
+        super();
+        this.catalogFactory = catalogFactory;
+    }
+    get description() {
+        return 'Verify warehouse tables and columns from the latest live-database scan before writing them into wiki or semantic-layer output.';
+    }
+    get inputSchema() {
+        return entityDetailsInputSchema;
+    }
+    async call(input, context) {
+        const allowed = allowedConnectionNames(context);
+        if (allowed && !allowed.has(input.connectionId)) {
+            return {
+                markdown: `Connection "${input.connectionId}" is not available to this ingest stage.`,
+                structured: { resolved: [], missing: [], scanAvailable: false },
+            };
+        }
+        const catalog = this.catalogFactory(context);
+        const scanAvailable = await catalog.hasScan(input.connectionId);
+        if (!scanAvailable) {
+            return {
+                markdown: `No live-database scan available for connection "${input.connectionId}"; run \`ktx scan\` first.`,
+                structured: { resolved: [], missing: [], scanAvailable: false },
+            };
+        }
+        const parts = [];
+        const resolved = [];
+        const missing = [];
+        for (const target of input.targets) {
+            const resolution = await resolveTarget(catalog, input.connectionId, target);
+            if (!resolution.resolved) {
+                missing.push({ target, candidates: resolution.candidates });
+                appendMissingTargetMarkdown(parts, target, resolution.candidates);
+                continue;
+            }
+            const detail = await catalog.getTable({ connectionId: input.connectionId, ...resolution.resolved });
+            if (!detail) {
+                missing.push({ target, candidates: resolution.candidates });
+                appendMissingTargetMarkdown(parts, target, resolution.candidates);
+                continue;
+            }
+            const requestedColumn = resolution.resolved.column;
+            if (requestedColumn) {
+                const column = findColumn(detail, requestedColumn);
+                if (!column) {
+                    missing.push({
+                        target,
+                        candidates: [{ catalog: detail.catalog, db: detail.db, name: detail.name }],
+                    });
+                    parts.push(`Column not found in scan: ${detail.display}.${requestedColumn}`);
+                    parts.push(`Available columns: ${detail.columns.map((candidate) => candidate.name).join(', ')}`);
+                    continue;
+                }
+                const scopedDetail = { ...detail, columns: [column] };
+                resolved.push(scopedDetail);
+                appendTableMarkdown(parts, scopedDetail, column.name);
+                continue;
+            }
+            resolved.push(detail);
+            appendTableMarkdown(parts, detail);
+        }
+        return {
+            markdown: parts.join('\n').trim(),
+            structured: { resolved, missing, scanAvailable: true },
+        };
+    }
+}

package/node_modules/@ktx/context/dist/ingest/tools/warehouse-verification/entity-details.tool.test.d.ts

@@ -0,0 +1 @@
+export {};