@kaelio/ktx 0.4.1 → 0.5.0

package/dist/context/ingest/adapters/historic-sql/connection-dialect.js

@@ -0,0 +1,30 @@
+function recordOrNull(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+function queryHistoryRecord(connection) {
+    const conn = recordOrNull(connection);
+    const context = conn ? recordOrNull(conn.context) : null;
+    return context ? recordOrNull(context.queryHistory) : null;
+}
+export function isQueryHistoryEnabled(connection) {
+    return queryHistoryRecord(connection)?.enabled === true;
+}
+/**
+ * Resolves the query-history dialect for a connection. Returns null when
+ * query history is disabled, or when the connection's driver has no
+ * query-history reader.
+ */
+export function queryHistoryDialectForConnection(connection) {
+    if (!isQueryHistoryEnabled(connection)) {
+        return null;
+    }
+    const conn = recordOrNull(connection);
+    const driver = String(conn?.driver ?? '').toLowerCase();
+    if (driver === 'postgres' || driver === 'postgresql')
+        return 'postgres';
+    if (driver === 'bigquery')
+        return 'bigquery';
+    if (driver === 'snowflake')
+        return 'snowflake';
+    return null;
+}

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

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+/** @internal */
+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>;
+/** @internal */
+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 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/dist/context/ingest/adapters/historic-sql/evidence.js

@@ -0,0 +1,34 @@
+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;
+}
+/** @internal */
+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,
+});
+/** @internal */
+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/dist/context/ingest/adapters/historic-sql/local-ingest-acceptance.test.js

@@ -0,0 +1,235 @@
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import YAML from 'yaml';
+import { initKtxProject, loadKtxProject } from '../../../../context/project/project.js';
+import { searchLocalSlSources } from '../../../sl/local-sl.js';
+import { searchLocalKnowledgePages } from '../../../wiki/local-knowledge.js';
+import { runLocalIngest } from '../../local-ingest.js';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { HistoricSqlSourceAdapter } from './historic-sql.adapter.js';
+class AcceptanceHistoricSqlReader {
+    async probe() {
+        return { warnings: [], info: [] };
+    }
+    async *fetchAggregated(_client, _window, _config) {
+        yield {
+            templateId: 'pg:orders-lifecycle',
+            canonicalSql: 'select o.status, c.segment, count(*) from public.orders o join public.customers c on c.id = o.customer_id where o.status = $1 group by o.status, c.segment',
+            dialect: 'postgres',
+            stats: {
+                executions: 42,
+                distinctUsers: 4,
+                firstSeen: '2026-05-01T00:00:00.000Z',
+                lastSeen: '2026-05-11T00:00:00.000Z',
+                p50RuntimeMs: 18,
+                p95RuntimeMs: 84,
+                errorRate: 0,
+                rowsProduced: 420,
+            },
+            topUsers: [{ user: 'analyst@example.test', executions: 42 }],
+        };
+    }
+}
+class HistoricSqlAcceptanceAgentRunner {
+    runLoop = vi.fn(async (params) => {
+        if (params.telemetryTags?.operationName !== 'ingest-bundle-wu') {
+            return { stopReason: 'natural' };
+        }
+        const emitEvidence = params.toolSet.emit_historic_sql_evidence;
+        if (!emitEvidence?.execute) {
+            throw new Error('emit_historic_sql_evidence tool was not available to the historic-SQL WorkUnit');
+        }
+        if (params.telemetryTags.unitKey === 'historic-sql-table-public-orders') {
+            const result = await emitEvidence.execute({
+                kind: 'table_usage',
+                table: 'public.orders',
+                rawPath: 'tables/public.orders.json',
+                usage: {
+                    narrative: 'Analysts repeatedly inspect paid order lifecycle by customer segment.',
+                    frequencyTier: 'high',
+                    commonFilters: ['status'],
+                    commonGroupBys: ['status', 'segment'],
+                    commonJoins: [{ table: 'public.customers', on: ['customer_id', 'id'] }],
+                    staleSince: null,
+                },
+            });
+            if (!result.markdown.includes('Recorded historic-SQL table_usage evidence')) {
+                throw new Error(`Unexpected orders evidence result: ${result.markdown}`);
+            }
+        }
+        if (params.telemetryTags.unitKey === 'historic-sql-table-public-customers') {
+            const result = await emitEvidence.execute({
+                kind: 'table_usage',
+                table: 'public.customers',
+                rawPath: 'tables/public.customers.json',
+                usage: {
+                    narrative: 'Customers provide segment context for paid order lifecycle analysis.',
+                    frequencyTier: 'mid',
+                    commonFilters: [],
+                    commonGroupBys: ['segment'],
+                    commonJoins: [{ table: 'public.orders', on: ['id', 'customer_id'] }],
+                    staleSince: null,
+                },
+            });
+            if (!result.markdown.includes('Recorded historic-SQL table_usage evidence')) {
+                throw new Error(`Unexpected customers evidence result: ${result.markdown}`);
+            }
+        }
+        if (params.telemetryTags.unitKey === 'historic-sql-patterns-part-0001') {
+            const result = await emitEvidence.execute({
+                kind: 'pattern',
+                rawPath: 'patterns-input/part-0001.json',
+                pattern: {
+                    slug: 'paid-order-lifecycle',
+                    title: 'Paid Order Lifecycle',
+                    narrative: 'Analysts join orders and customers to compare paid order lifecycle by segment.',
+                    definitionSql: 'select o.status, c.segment, count(*) from public.orders o join public.customers c on c.id = o.customer_id group by o.status, c.segment',
+                    tablesInvolved: ['public.orders', 'public.customers'],
+                    slRefs: ['orders', 'customers'],
+                    constituentTemplateIds: ['pg:orders-lifecycle'],
+                },
+            });
+            if (!result.markdown.includes('Recorded historic-SQL pattern evidence')) {
+                throw new Error(`Unexpected pattern evidence result: ${result.markdown}`);
+            }
+        }
+        return { stopReason: 'natural' };
+    });
+}
+function acceptanceSqlAnalysis() {
+    return {
+        analyzeForFingerprint: async () => {
+            throw new Error('analyzeForFingerprint should not be used by unified historic-SQL ingest');
+        },
+        analyzeBatch: vi.fn(async (items, _dialect) => {
+            return new Map(items.map((item) => [
+                item.id,
+                {
+                    tablesTouched: ['public.orders', 'public.customers'],
+                    columnsByClause: {
+                        select: ['status', 'segment'],
+                        where: ['status'],
+                        join: ['customer_id', 'id'],
+                        groupBy: ['status', 'segment'],
+                    },
+                },
+            ]));
+        }),
+        validateReadOnly: vi.fn(async () => ({ ok: true })),
+    };
+}
+async function writeHistoricSqlProject(project) {
+    await writeFile(join(project.projectDir, 'ktx.yaml'), [
+        'connections:',
+        '  warehouse:',
+        '    driver: postgres',
+        '    context:',
+        '      queryHistory:',
+        '        enabled: true',
+        '        minExecutions: 2',
+        'ingest:',
+        '  adapters:',
+        '    - historic-sql',
+        '  embeddings:',
+        '    backend: none',
+        'storage:',
+        '  state: sqlite',
+        '  search: sqlite-fts5',
+        '  git:',
+        '    auto_commit: false',
+        '    author: KTX Test <system@ktx.local>',
+        '',
+    ].join('\n'), 'utf-8');
+    const loaded = await loadKtxProject({ projectDir: project.projectDir });
+    await loaded.fileStore.writeFile('semantic-layer/warehouse/_schema/public.yaml', YAML.stringify({
+        tables: {
+            orders: {
+                table: 'public.orders',
+                columns: [
+                    { name: 'id', type: 'string' },
+                    { name: 'status', type: 'string' },
+                    { name: 'customer_id', type: 'string' },
+                ],
+            },
+            customers: {
+                table: 'public.customers',
+                columns: [
+                    { name: 'id', type: 'string' },
+                    { name: 'segment', type: 'string' },
+                ],
+            },
+        },
+    }), 'KTX Test', 'system@ktx.local', 'Seed schema shard');
+    return loaded;
+}
+describe('historic-SQL local ingest retrieval acceptance', () => {
+    let tempDir;
+    beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'ktx-historic-sql-acceptance-'));
+    });
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+    it('projects table and pattern evidence into semantic-layer and wiki retrieval surfaces', async () => {
+        const initialized = await initKtxProject({ projectDir: join(tempDir, 'project') });
+        const project = await writeHistoricSqlProject(initialized);
+        const sqlAnalysis = acceptanceSqlAnalysis();
+        const agentRunner = new HistoricSqlAcceptanceAgentRunner();
+        const adapter = new HistoricSqlSourceAdapter({
+            reader: new AcceptanceHistoricSqlReader(),
+            queryClient: {},
+            sqlAnalysis,
+            now: () => new Date('2026-05-11T00:00:00.000Z'),
+        });
+        const result = await runLocalIngest({
+            project,
+            adapters: [adapter],
+            adapter: 'historic-sql',
+            connectionId: 'warehouse',
+            jobId: 'historic-sql-retrieval-acceptance',
+            agentRunner,
+        });
+        expect(sqlAnalysis.analyzeBatch).toHaveBeenCalledTimes(1);
+        expect(result.result.failedWorkUnits).toEqual([]);
+        expect(result.result.workUnitCount).toBe(3);
+        expect(agentRunner.runLoop).toHaveBeenCalledTimes(3);
+        const finalization = result.report.body.finalization;
+        expect(finalization).toBeDefined();
+        if (!finalization) {
+            throw new Error('Expected historic-SQL finalization result');
+        }
+        expect(finalization).toMatchObject({
+            sourceKey: 'historic-sql',
+            status: 'success',
+            result: {
+                tableUsageMerged: 2,
+                patternPagesWritten: 1,
+            },
+        });
+        expect(finalization.declaredTouchedSources).toEqual(expect.arrayContaining([
+            { connectionId: 'warehouse', sourceName: 'customers' },
+            { connectionId: 'warehouse', sourceName: 'orders' },
+        ]));
+        await expect(readFile(join(project.projectDir, 'semantic-layer/warehouse/_schema/public.yaml'), 'utf-8')).resolves
+            .toContain('Analysts repeatedly inspect paid order lifecycle by customer segment.');
+        await expect(readFile(join(project.projectDir, 'wiki/global/historic-sql-paid-order-lifecycle.md'), 'utf-8'))
+            .resolves.toContain('Paid Order Lifecycle');
+        const reloaded = await loadKtxProject({ projectDir: project.projectDir });
+        await expect(searchLocalSlSources(reloaded, { connectionId: 'warehouse', query: 'paid order lifecycle', limit: 5 })).resolves.toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                name: 'orders',
+                frequencyTier: 'high',
+                snippet: expect.stringContaining('<mark>'),
+                matchReasons: expect.arrayContaining(['lexical']),
+            }),
+        ]));
+        await expect(searchLocalKnowledgePages(reloaded, { query: 'paid order lifecycle', userId: 'local', limit: 5 })).resolves.toEqual([
+            expect.objectContaining({
+                key: 'historic-sql-paid-order-lifecycle',
+                summary: 'Paid Order Lifecycle',
+                matchReasons: expect.arrayContaining(['lexical']),
+            }),
+        ]);
+    });
+});

package/dist/context/ingest/adapters/historic-sql/pattern-inputs.d.ts

@@ -0,0 +1,21 @@
+import type { StagedPatternsInput } from './types.js';
+/** @internal */
+export declare const HISTORIC_SQL_PATTERN_WORKUNIT_MAX_BYTES = 110000;
+interface HistoricSqlPatternInputShard {
+    path: string;
+    input: StagedPatternsInput;
+    byteLength: number;
+}
+export interface HistoricSqlPatternInputSplitResult {
+    auditInput: StagedPatternsInput;
+    shards: HistoricSqlPatternInputShard[];
+    warnings: string[];
+}
+export interface HistoricSqlPatternInputSplitOptions {
+    maxBytes?: number;
+}
+export declare function isHistoricSqlPatternInputShardPath(path: string): boolean;
+/** @internal */
+export declare function serializedStagedPatternsInputByteLength(input: StagedPatternsInput): number;
+export declare function splitHistoricSqlPatternInputs(input: StagedPatternsInput, options?: HistoricSqlPatternInputSplitOptions): HistoricSqlPatternInputSplitResult;
+export {};

package/dist/context/ingest/adapters/historic-sql/pattern-inputs.js

@@ -0,0 +1,68 @@
+import { Buffer } from 'node:buffer';
+const HISTORIC_SQL_PATTERN_WORKUNIT_DIR = 'patterns-input';
+/** @internal */
+export const HISTORIC_SQL_PATTERN_WORKUNIT_MAX_BYTES = 110_000;
+const HISTORIC_SQL_PATTERN_WORKUNIT_PATH_RE = /^patterns-input\/part-\d{4}\.json$/;
+export function isHistoricSqlPatternInputShardPath(path) {
+    return HISTORIC_SQL_PATTERN_WORKUNIT_PATH_RE.test(path);
+}
+function serializeStagedPatternsInput(input) {
+    return `${JSON.stringify(input, null, 2)}\n`;
+}
+/** @internal */
+export function serializedStagedPatternsInputByteLength(input) {
+    return Buffer.byteLength(serializeStagedPatternsInput(input), 'utf-8');
+}
+function sortedAuditTemplates(templates) {
+    return [...templates].sort((left, right) => left.id.localeCompare(right.id));
+}
+function sortedPatternCandidates(templates) {
+    return [...templates]
+        .filter((template) => template.tablesTouched.length >= 2)
+        .map((template) => ({ ...template, tablesTouched: [...template.tablesTouched].sort() }))
+        .sort((left, right) => {
+        const cardinality = right.tablesTouched.length - left.tablesTouched.length;
+        if (cardinality !== 0)
+            return cardinality;
+        const tableSignature = left.tablesTouched.join('\0').localeCompare(right.tablesTouched.join('\0'));
+        if (tableSignature !== 0)
+            return tableSignature;
+        return left.id.localeCompare(right.id);
+    });
+}
+function shardPath(index) {
+    return `${HISTORIC_SQL_PATTERN_WORKUNIT_DIR}/part-${String(index).padStart(4, '0')}.json`;
+}
+export function splitHistoricSqlPatternInputs(input, options = {}) {
+    const maxBytes = options.maxBytes ?? HISTORIC_SQL_PATTERN_WORKUNIT_MAX_BYTES;
+    const auditInput = { templates: sortedAuditTemplates(input.templates) };
+    const warnings = [];
+    const shards = [];
+    let current = [];
+    const flush = () => {
+        if (current.length === 0) {
+            return;
+        }
+        const shardInput = { templates: current };
+        shards.push({
+            path: shardPath(shards.length + 1),
+            input: shardInput,
+            byteLength: serializedStagedPatternsInputByteLength(shardInput),
+        });
+        current = [];
+    };
+    for (const template of sortedPatternCandidates(input.templates)) {
+        const singleInput = { templates: [template] };
+        if (serializedStagedPatternsInputByteLength(singleInput) > maxBytes) {
+            warnings.push(`patterns_input_template_too_large:${template.id}`);
+            continue;
+        }
+        const nextInput = { templates: [...current, template] };
+        if (current.length > 0 && serializedStagedPatternsInputByteLength(nextInput) > maxBytes) {
+            flush();
+        }
+        current.push(template);
+    }
+    flush();
+    return { auditInput, shards, warnings };
+}

package/dist/context/ingest/adapters/historic-sql/projection.d.ts

@@ -0,0 +1,24 @@
+import type { MemoryAction } from '../../../../context/memory/types.js';
+import type { FinalizationOverrideReplay } from '../../types.js';
+export interface HistoricSqlProjectionInput {
+    workdir: string;
+    connectionId: string;
+    syncId: string;
+    runId: string;
+    overrideReplay?: FinalizationOverrideReplay;
+}
+export interface HistoricSqlProjectionResult {
+    tableUsageMerged: number;
+    staleTablesMarked: number;
+    patternPagesWritten: number;
+    stalePatternPagesMarked: number;
+    archivedPatternPages: number;
+    touchedSources: Array<{
+        connectionId: string;
+        sourceName: string;
+    }>;
+    changedWikiPageKeys: string[];
+    actions: MemoryAction[];
+    warnings: string[];
+}
+export declare function projectHistoricSqlEvidence(input: HistoricSqlProjectionInput): Promise<HistoricSqlProjectionResult>;

package/dist/context/ingest/adapters/historic-sql/skill-schemas.d.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+export declare const tableUsageOutputSchema: 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>;
+export type TableUsageOutput = z.infer<typeof tableUsageOutputSchema>;
+export declare const patternOutputSchema: 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>;
+/** @internal */
+export declare const patternsArraySchema: z.ZodArray<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>>;

package/dist/context/ingest/adapters/historic-sql/skill-schemas.js

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+export const tableUsageOutputSchema = z
+    .object({
+    narrative: z.string(),
+    frequencyTier: z.enum(['high', 'mid', 'low', 'unused']),
+    commonFilters: z.array(z.string()),
+    commonGroupBys: z.array(z.string()).optional(),
+    commonJoins: z.array(z.object({
+        table: z.string(),
+        on: z.array(z.string()),
+    })),
+    staleSince: z.iso.datetime().nullable().optional(),
+})
+    .passthrough();
+export const patternOutputSchema = z.object({
+    slug: z.string(),
+    title: z.string(),
+    narrative: z.string(),
+    definitionSql: z.string(),
+    tablesInvolved: z.array(z.string()),
+    slRefs: z.array(z.string()),
+    constituentTemplateIds: z.array(z.string()),
+});
+/** @internal */
+export const patternsArraySchema = z.array(patternOutputSchema);

package/dist/context/ingest/adapters/historic-sql/stage-unified.d.ts

@@ -0,0 +1,13 @@
+import type { SqlAnalysisPort } from '../../../../context/sql-analysis/ports.js';
+import { type HistoricSqlReader } from './types.js';
+interface StageHistoricSqlAggregatedSnapshotInput {
+    stagedDir: string;
+    connectionId: string;
+    queryClient: unknown;
+    reader: HistoricSqlReader;
+    sqlAnalysis: SqlAnalysisPort;
+    pullConfig: unknown;
+    now?: Date;
+}
+export declare function stageHistoricSqlAggregatedSnapshot(input: StageHistoricSqlAggregatedSnapshotInput): Promise<void>;
+export {};