@kaelio/ktx 0.0.0 → 0.1.0-rc.1

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/evidence-tool.d.ts

@@ -0,0 +1,41 @@
+interface EmitHistoricSqlEvidenceToolContext {
+    connectionId?: string | null;
+    session?: {
+        ingest?: {
+            runId: string;
+            sourceKey: string;
+        };
+        configService?: {
+            writeFile(path: string, content: string, author: string, authorEmail: string, commitMessage: string, options?: {
+                skipLock?: boolean;
+            }): Promise<unknown>;
+        };
+    };
+}
+export declare function createEmitHistoricSqlEvidenceTool(defaultContext?: EmitHistoricSqlEvidenceToolContext): import("ai").Tool<{
+    kind: "pattern" | "table_usage";
+    rawPath: string;
+    table?: string | undefined;
+    usage?: {
+        [x: string]: unknown;
+        narrative: string;
+        frequencyTier: "high" | "mid" | "low" | "unused";
+        commonFilters: string[];
+        commonJoins: {
+            table: string;
+            on: string[];
+        }[];
+        commonGroupBys?: string[] | undefined;
+        staleSince?: string | null | undefined;
+    } | undefined;
+    pattern?: {
+        slug: string;
+        title: string;
+        narrative: string;
+        definitionSql: string;
+        tablesInvolved: string[];
+        slRefs: string[];
+        constituentTemplateIds: string[];
+    } | undefined;
+}, string>;
+export {};

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/evidence-tool.js

@@ -0,0 +1,88 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import { historicSqlEvidencePath, serializeHistoricSqlEvidence } from './evidence.js';
+import { patternOutputSchema, tableUsageOutputSchema } from './skill-schemas.js';
+const SYSTEM_AUTHOR = 'System User';
+const SYSTEM_EMAIL = 'system@example.com';
+const emitHistoricSqlEvidenceInputSchema = z
+    .object({
+    kind: z.enum(['table_usage', 'pattern']),
+    table: z.string().min(1).optional(),
+    rawPath: z.string().min(1),
+    usage: tableUsageOutputSchema.optional(),
+    pattern: patternOutputSchema.optional(),
+})
+    .superRefine((input, ctx) => {
+    if (input.kind === 'table_usage') {
+        if (!input.table) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['table'],
+                message: 'table is required when kind is table_usage',
+            });
+        }
+        if (!input.usage) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['usage'],
+                message: 'usage is required when kind is table_usage',
+            });
+        }
+    }
+    if (input.kind === 'pattern' && !input.pattern) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['pattern'],
+            message: 'pattern is required when kind is pattern',
+        });
+    }
+});
+function unitKeyForEvidence(input) {
+    if (input.kind === 'table_usage') {
+        return `historic-sql-table-${String(input.table).replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-+|-+$/g, '')}`;
+    }
+    return `historic-sql-pattern-${String(input.pattern?.slug).replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-+|-+$/g, '')}`;
+}
+function evidenceEnvelope(input, connectionId) {
+    if (input.kind === 'table_usage') {
+        if (!input.table || !input.usage) {
+            throw new Error('Invalid historic-SQL table usage evidence input.');
+        }
+        return {
+            kind: 'table_usage',
+            connectionId,
+            table: input.table,
+            rawPath: input.rawPath,
+            usage: input.usage,
+        };
+    }
+    if (!input.pattern) {
+        throw new Error('Invalid historic-SQL pattern evidence input.');
+    }
+    return {
+        kind: 'pattern',
+        connectionId,
+        rawPath: input.rawPath,
+        pattern: input.pattern,
+    };
+}
+export function createEmitHistoricSqlEvidenceTool(defaultContext) {
+    return tool({
+        description: 'Record typed historic-SQL evidence for deterministic projection. Use this instead of wiki_write, sl_write_source, sl_edit_source, or context_candidate_write during historic-SQL WorkUnits.',
+        inputSchema: emitHistoricSqlEvidenceInputSchema,
+        execute: async (input, options) => {
+            const context = options.experimental_context ?? defaultContext;
+            const ingest = context?.session?.ingest;
+            const configService = context?.session?.configService;
+            if (!ingest || ingest.sourceKey !== 'historic-sql' || !configService || !context?.connectionId) {
+                return 'Error: emit_historic_sql_evidence is only available during historic-sql ingest.';
+            }
+            const unitKey = unitKeyForEvidence(input);
+            const evidence = evidenceEnvelope(input, context.connectionId);
+            const content = serializeHistoricSqlEvidence(evidence);
+            await configService.writeFile(historicSqlEvidencePath(ingest.runId, unitKey), content, SYSTEM_AUTHOR, SYSTEM_EMAIL, `Record historic-SQL evidence: ${unitKey}`, { skipLock: true });
+            const label = evidence.kind === 'table_usage' ? evidence.table : evidence.pattern.slug;
+            return `Recorded historic-SQL ${input.kind} evidence for ${label}.`;
+        },
+    });
+}

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/evidence-tool.test.d.ts

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

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/evidence-tool.test.js

@@ -0,0 +1,67 @@
+import { describe, expect, it, vi } from 'vitest';
+import { asSchema } from 'ai';
+import { createEmitHistoricSqlEvidenceTool } from './evidence-tool.js';
+describe('emit_historic_sql_evidence tool', () => {
+    it('exposes an AI SDK v6 tool input schema with top-level object type', async () => {
+        const tool = createEmitHistoricSqlEvidenceTool();
+        expect(await asSchema(tool.inputSchema).jsonSchema).toMatchObject({
+            type: 'object',
+        });
+    });
+    it('writes table usage evidence to the ignored run evidence directory', async () => {
+        const writeFile = vi.fn(async () => ({ success: true, commitHash: null }));
+        const tool = createEmitHistoricSqlEvidenceTool();
+        const result = await tool.execute({
+            kind: 'table_usage',
+            table: 'public.orders',
+            rawPath: 'tables/public.orders.json',
+            usage: {
+                narrative: 'Orders are repeatedly queried by paid status.',
+                frequencyTier: 'high',
+                commonFilters: ['status'],
+                commonJoins: [],
+                staleSince: null,
+            },
+        }, {
+            toolCallId: 'call-1',
+            messages: [],
+            abortSignal: new AbortController().signal,
+            experimental_context: {
+                connectionId: 'warehouse',
+                session: {
+                    ingest: { runId: 'run-1', jobId: 'job-1', syncId: 'sync-1', sourceKey: 'historic-sql' },
+                    configService: { writeFile },
+                },
+            },
+        });
+        expect(result).toBe('Recorded historic-SQL table_usage evidence for public.orders.');
+        expect(writeFile).toHaveBeenCalledWith('.ktx/ingest-evidence/historic-sql/run-1/historic-sql-table-public-orders.json', expect.stringContaining('"kind": "table_usage"'), 'System User', 'system@example.com', 'Record historic-SQL evidence: historic-sql-table-public-orders', { skipLock: true });
+    });
+    it('rejects non-historic ingest sessions', async () => {
+        const tool = createEmitHistoricSqlEvidenceTool();
+        await expect(tool.execute({
+            kind: 'pattern',
+            rawPath: 'patterns-input.json',
+            pattern: {
+                slug: 'orders',
+                title: 'Orders',
+                narrative: 'Orders pattern.',
+                definitionSql: 'select * from public.orders',
+                tablesInvolved: ['public.orders'],
+                slRefs: ['orders'],
+                constituentTemplateIds: ['pg:1'],
+            },
+        }, {
+            toolCallId: 'call-1',
+            messages: [],
+            abortSignal: new AbortController().signal,
+            experimental_context: {
+                connectionId: 'warehouse',
+                session: {
+                    ingest: { runId: 'run-1', jobId: 'job-1', syncId: 'sync-1', sourceKey: 'notion' },
+                    configService: { writeFile: vi.fn() },
+                },
+            },
+        })).resolves.toContain('Error: emit_historic_sql_evidence is only available during historic-sql ingest');
+    });
+});

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/evidence.d.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+export declare const historicSqlTableUsageEvidenceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"table_usage">;
+    connectionId: z.ZodString;
+    table: z.ZodString;
+    rawPath: z.ZodString;
+    usage: z.ZodObject<{
+        narrative: z.ZodString;
+        frequencyTier: z.ZodEnum<{
+            high: "high";
+            mid: "mid";
+            low: "low";
+            unused: "unused";
+        }>;
+        commonFilters: z.ZodArray<z.ZodString>;
+        commonGroupBys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        commonJoins: z.ZodArray<z.ZodObject<{
+            table: z.ZodString;
+            on: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+        staleSince: z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>;
+    }, z.core.$loose>;
+}, z.core.$strip>;
+export type HistoricSqlTableUsageEvidence = z.infer<typeof historicSqlTableUsageEvidenceSchema>;
+export declare const historicSqlPatternEvidenceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"pattern">;
+    connectionId: z.ZodString;
+    rawPath: z.ZodString;
+    pattern: z.ZodObject<{
+        slug: z.ZodString;
+        title: z.ZodString;
+        narrative: z.ZodString;
+        definitionSql: z.ZodString;
+        tablesInvolved: z.ZodArray<z.ZodString>;
+        slRefs: z.ZodArray<z.ZodString>;
+        constituentTemplateIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type HistoricSqlPatternEvidence = z.infer<typeof historicSqlPatternEvidenceSchema>;
+export declare const historicSqlEvidenceEnvelopeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"table_usage">;
+    connectionId: z.ZodString;
+    table: z.ZodString;
+    rawPath: z.ZodString;
+    usage: z.ZodObject<{
+        narrative: z.ZodString;
+        frequencyTier: z.ZodEnum<{
+            high: "high";
+            mid: "mid";
+            low: "low";
+            unused: "unused";
+        }>;
+        commonFilters: z.ZodArray<z.ZodString>;
+        commonGroupBys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        commonJoins: z.ZodArray<z.ZodObject<{
+            table: z.ZodString;
+            on: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+        staleSince: z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>;
+    }, z.core.$loose>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"pattern">;
+    connectionId: z.ZodString;
+    rawPath: z.ZodString;
+    pattern: z.ZodObject<{
+        slug: z.ZodString;
+        title: z.ZodString;
+        narrative: z.ZodString;
+        definitionSql: z.ZodString;
+        tablesInvolved: z.ZodArray<z.ZodString>;
+        slRefs: z.ZodArray<z.ZodString>;
+        constituentTemplateIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>], "kind">;
+export type HistoricSqlEvidenceEnvelope = z.infer<typeof historicSqlEvidenceEnvelopeSchema>;
+export declare function historicSqlEvidencePath(runId: string, unitKey: string): string;
+export declare function serializeHistoricSqlEvidence(evidence: HistoricSqlEvidenceEnvelope): string;

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/evidence.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { patternOutputSchema, tableUsageOutputSchema } from './skill-schemas.js';
+function safeEvidenceSegment(value) {
+    const segment = value.replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+    if (!segment) {
+        throw new Error(`Invalid historic-SQL evidence path segment: ${value}`);
+    }
+    return segment;
+}
+export const historicSqlTableUsageEvidenceSchema = z.object({
+    kind: z.literal('table_usage'),
+    connectionId: z.string().min(1),
+    table: z.string().min(1),
+    rawPath: z.string().min(1),
+    usage: tableUsageOutputSchema,
+});
+export const historicSqlPatternEvidenceSchema = z.object({
+    kind: z.literal('pattern'),
+    connectionId: z.string().min(1),
+    rawPath: z.string().min(1),
+    pattern: patternOutputSchema,
+});
+export const historicSqlEvidenceEnvelopeSchema = z.discriminatedUnion('kind', [
+    historicSqlTableUsageEvidenceSchema,
+    historicSqlPatternEvidenceSchema,
+]);
+export function historicSqlEvidencePath(runId, unitKey) {
+    return `.ktx/ingest-evidence/historic-sql/${safeEvidenceSegment(runId)}/${safeEvidenceSegment(unitKey)}.json`;
+}
+export function serializeHistoricSqlEvidence(evidence) {
+    return `${JSON.stringify(historicSqlEvidenceEnvelopeSchema.parse(evidence), null, 2)}\n`;
+}

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/evidence.test.d.ts

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

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/evidence.test.js

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { historicSqlEvidenceEnvelopeSchema, historicSqlEvidencePath, historicSqlPatternEvidenceSchema, historicSqlTableUsageEvidenceSchema, } from './evidence.js';
+describe('historic-sql evidence contracts', () => {
+    it('validates table usage evidence emitted by table digest WorkUnits', () => {
+        const parsed = historicSqlTableUsageEvidenceSchema.parse({
+            kind: 'table_usage',
+            connectionId: 'warehouse',
+            table: 'public.orders',
+            rawPath: 'tables/public.orders.json',
+            usage: {
+                narrative: 'Orders are repeatedly queried for paid/refunded lifecycle analysis.',
+                frequencyTier: 'high',
+                commonFilters: ['status', 'created_at'],
+                commonGroupBys: ['status'],
+                commonJoins: [{ table: 'public.customers', on: ['customer_id'] }],
+                staleSince: null,
+            },
+        });
+        expect(parsed.table).toBe('public.orders');
+        expect(parsed.usage.frequencyTier).toBe('high');
+    });
+    it('validates pattern evidence emitted by the patterns WorkUnit', () => {
+        const parsed = historicSqlPatternEvidenceSchema.parse(historicSqlEvidenceEnvelopeSchema.parse({
+            kind: 'pattern',
+            connectionId: 'warehouse',
+            rawPath: 'patterns-input.json',
+            pattern: {
+                slug: 'order-lifecycle-analysis',
+                title: 'Order Lifecycle Analysis',
+                narrative: 'Analysts compare order status changes by customer segment.',
+                definitionSql: 'select status, count(*) from public.orders group by status',
+                tablesInvolved: ['public.orders', 'public.customers'],
+                slRefs: ['orders', 'customers'],
+                constituentTemplateIds: ['pg:1', 'pg:2'],
+            },
+        }));
+        expect(parsed.kind).toBe('pattern');
+        expect(parsed.pattern.slug).toBe('order-lifecycle-analysis');
+    });
+    it('builds a stable ignored evidence path from run and WorkUnit identity', () => {
+        expect(historicSqlEvidencePath('run-1', 'historic-sql-table-public-orders')).toBe('.ktx/ingest-evidence/historic-sql/run-1/historic-sql-table-public-orders.json');
+    });
+});

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/historic-sql.adapter.d.ts

@@ -0,0 +1,14 @@
+import type { ChunkResult, DiffSet, FetchContext, ScopeDescriptor, SourceAdapter } from '../../types.js';
+import { type HistoricSqlSourceAdapterDeps } from './types.js';
+export declare class HistoricSqlSourceAdapter implements SourceAdapter {
+    private readonly deps;
+    readonly source = "historic-sql";
+    readonly skillNames: string[];
+    readonly reconcileSkillNames: string[];
+    readonly triageSupported = false;
+    constructor(deps: HistoricSqlSourceAdapterDeps);
+    detect(stagedDir: string): Promise<boolean>;
+    fetch(pullConfig: unknown, stagedDir: string, ctx: FetchContext): Promise<void>;
+    chunk(stagedDir: string, diffSet?: DiffSet): Promise<ChunkResult>;
+    describeScope(stagedDir: string): Promise<ScopeDescriptor>;
+}

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/historic-sql.adapter.js

@@ -0,0 +1,33 @@
+import { chunkHistoricSqlUnifiedStagedDir, describeHistoricSqlUnifiedScope } from './chunk-unified.js';
+import { detectHistoricSqlStagedDir } from './detect.js';
+import { stageHistoricSqlAggregatedSnapshot } from './stage-unified.js';
+export class HistoricSqlSourceAdapter {
+    deps;
+    source = 'historic-sql';
+    skillNames = ['historic_sql_table_digest', 'historic_sql_patterns'];
+    reconcileSkillNames = [];
+    triageSupported = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    detect(stagedDir) {
+        return detectHistoricSqlStagedDir(stagedDir);
+    }
+    async fetch(pullConfig, stagedDir, ctx) {
+        await stageHistoricSqlAggregatedSnapshot({
+            stagedDir,
+            connectionId: ctx.connectionId,
+            queryClient: this.deps.queryClient,
+            reader: this.deps.reader,
+            sqlAnalysis: this.deps.sqlAnalysis,
+            pullConfig,
+            now: this.deps.now?.(),
+        });
+    }
+    chunk(stagedDir, diffSet) {
+        return chunkHistoricSqlUnifiedStagedDir(stagedDir, diffSet);
+    }
+    describeScope(stagedDir) {
+        return describeHistoricSqlUnifiedScope(stagedDir);
+    }
+}

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/historic-sql.adapter.test.d.ts

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

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/historic-sql.adapter.test.js

@@ -0,0 +1,98 @@
+import { mkdtemp } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { HistoricSqlSourceAdapter } from './historic-sql.adapter.js';
+async function tempDir() {
+    return mkdtemp(join(tmpdir(), 'historic-sql-adapter-'));
+}
+const sqlAnalysis = {
+    async analyzeForFingerprint() {
+        throw new Error('analyzeForFingerprint must not be used');
+    },
+    async analyzeBatch() {
+        return new Map();
+    },
+    async validateReadOnly() {
+        return { ok: true };
+    },
+};
+const reader = {
+    async probe() {
+        return { warnings: [], info: [] };
+    },
+    async *fetchAggregated() { },
+};
+describe('HistoricSqlSourceAdapter', () => {
+    it('declares canonical adapter metadata', () => {
+        const adapter = new HistoricSqlSourceAdapter({ sqlAnalysis, reader, queryClient: {} });
+        expect(adapter.source).toBe('historic-sql');
+        expect(adapter.skillNames).toEqual(['historic_sql_table_digest', 'historic_sql_patterns']);
+        expect(adapter.reconcileSkillNames).toEqual([]);
+        expect(adapter.evidenceIndexing).toBeUndefined();
+        expect(adapter.triageSupported).toBe(false);
+    });
+    it('fetches a unified aggregate snapshot and emits unified WorkUnits', async () => {
+        const stagedDir = await tempDir();
+        const aggregateReader = {
+            async probe() {
+                return { warnings: [], info: [] };
+            },
+            async *fetchAggregated() {
+                yield {
+                    templateId: 'pg:1',
+                    canonicalSql: 'select o.status, count(*) from public.orders o join public.customers c on c.id = o.customer_id group by o.status',
+                    dialect: 'postgres',
+                    stats: {
+                        executions: 25,
+                        distinctUsers: 3,
+                        firstSeen: '2026-05-01T00:00:00.000Z',
+                        lastSeen: '2026-05-11T00:00:00.000Z',
+                        p50RuntimeMs: 10,
+                        p95RuntimeMs: 20,
+                        errorRate: 0,
+                        rowsProduced: 10,
+                    },
+                    topUsers: [{ user: 'analyst', executions: 25 }],
+                };
+            },
+        };
+        const batchSqlAnalysis = {
+            async analyzeForFingerprint() {
+                throw new Error('analyzeForFingerprint must not be used');
+            },
+            async analyzeBatch() {
+                return new Map([
+                    [
+                        'pg:1',
+                        {
+                            tablesTouched: ['public.orders', 'public.customers'],
+                            columnsByClause: { select: ['status'], join: ['customer_id', 'id'], groupBy: ['status'] },
+                        },
+                    ],
+                ]);
+            },
+            async validateReadOnly() {
+                return { ok: true };
+            },
+        };
+        const adapter = new HistoricSqlSourceAdapter({
+            sqlAnalysis: batchSqlAnalysis,
+            reader: aggregateReader,
+            queryClient: {},
+            now: () => new Date('2026-05-11T00:00:00.000Z'),
+        });
+        await adapter.fetch({ dialect: 'postgres', minExecutions: 5 }, stagedDir, {
+            connectionId: 'warehouse',
+            sourceKey: 'historic-sql',
+        });
+        await expect(adapter.detect(stagedDir)).resolves.toBe(true);
+        await expect(adapter.chunk(stagedDir)).resolves.toMatchObject({
+            workUnits: [
+                { unitKey: 'historic-sql-table-public-customers' },
+                { unitKey: 'historic-sql-table-public-orders' },
+                { unitKey: 'historic-sql-patterns-part-0001' },
+            ],
+        });
+    });
+});

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/local-ingest-acceptance.test.d.ts

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